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This book describes all IBM data management except for VSAM 
(virtual storage access method) and specialised applications 
such as the time sharing option (TSO), graphics, teleprocessing, 
optical character readers, optical reader-sorters, and magnetic 
character readers. These specialised applications are described 
in separate publications that are listed in IBM Svstem/370 
Bibliographv ,GC20-00Q1. To learn about VSAM or to write programs 
that create and process VSAM data sets, refer to? 

• Planning for Enhanced VSAM Under OS/VS , GC26-3842, which 
introduces VSAM and describes its concepts and functions. 

• 05/VS Virtual Storage Access Method (VSAM) Programmer’s 
Guide , GC26-3838, which describes how to create VSAM data 
sets and code the macro instructions required to process 
them. 

• 0S/VS2 Access Method Services , GC26-3841, describes the 
service program commands used to manipulate VSAM data sets. 

• OS/VS Virtual Storage Access M e thod (VSAM) Options for 
Advanced Applications , GC26-3819, which describes 
applications not required in the normal use of VSAM. 

If you know how to write assemblei—language programs and use job 
control statements, you can use this book and 0S/VS2 MVS Data 
Management Macro Instructions , GC26-3873, to write programs that 
create and process data sets. To use this book you must have 
basic knowledge of the operating system as contained in 0S/VS2 
Release 3 Guide , GC28-0770; of assembler language as described 
in 0S/VS-D05/VS—VM/370 Assembler Language , GC33-4010; and of job 
control language (JCL) as explained in 0S/VS2 JCL , GC28-0692. 

This book has three parts: "Part 1: Introduction to Data 
Management" introduces you to the characteristics of data sets, 
how you name them, how the system catalogs them, and how you 
format the records in them. The format of tracks on a 
direct-access storage device is explained briefly. 

Part 1 also describes the data control block (DCB) and the 
information it supplies to the operating system. Special 
processing routines that you specify in the DCB macro 
instruction are also explained in this section. 

In "Part 2 ' Data Management Processing Procedures" there is an 
explanation of data-processing techniques that includes the 
macro instructions for the queued access technique and the basic 
access technique and the macro instructions for analysing input 
and output errors. The section on data-processing techniques 
also tells how to select an access method and how to begin and 
end processing of a data set. 

The section "Buffer Acquisition and Control" in Part 2 explains 
three different methods you can use to obtain buffers and the 
macro instructions you use with each method. This section also 
describes ways to control buffers: simple buffering for the 
queued access technique, direct buffering and dynamic buffering 
for the basic access technique. In addition, for the queued 
access technique, there is an explanation of the four modes of 
moving the records in virtual storage: move mode, data mode, 
locate mode, and substitute mode. Macro instructions for 
controlling buffers are described here, too. 

The next four sections of Part 2 concern processing data sets of 
four different types: a sequential data set, a partitioned data 
set, an indexed sequential data set, and a direct data set. They 
explain the organisation of the data sets and the macro 
instructions used to process them. In the examples the macro 
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instructions are coded in just enough detail to make the 
examples clear. For a complete description of the operands and 
options available, see QS/VS2 MVS Data M a nagement Macro 
Instructions , GC26-3873. "Part 3: Data Set Disposition and Space 
Allocation" tells you how to figure the amount of space you need 
for a data set on a direct-access storage device and how to 
request that space in your JCL DD statement. You are given 
special directions for allocating space for a partitioned data 
set and an indexed sequential data set. Part 3 also tells how to 
indicate in the JCL DD statement the status of the data set at 
the beginning of and during processing and how to indicate what 
you want the system to do with the data set when processing has 
terminated. You also are told how to use the DD statement to 
route the data set to a system output writer, to concatenate 
data sets, to catalog data sets, and to protect confidential 
data sets. 

Appendix A describes data set labeling. Appendix B explains 
control characters you can use to control card punches and 
printers. A glossary of acronyms and abbreviations used in this 
book and the index follow Appendix B. 

The following manuals are referred to in the text. 


OS/VS Message Library* VS2 System Codes, GC38-1008 


OS/VS Message Library* VS2 System Messages , GC38-1002 

0S/VS2 JCL , GC28-0692 

QS/VS2 MVS CVOL Processor , GC26-3864 

Q5/VS2 MVS Resource Access Control Facility (RACF)» General 
Information Manual , GC28-0722 

0S/VS2 Supervisor Services and Macro Instructions , GC28-0683 

0S/VS2 System Programming Library? Data Management , 

GC26-3830 

0S/VS2 System Programming Library? Debugging Handbook, 

Volume 1, GC28-Q708 


0S/VS2 System Programming Library 
Volume 2 , GC28-0709 

0S/VS2 System Programming Li bran 
Volume 3, GC28-0710 


Debugging Handbook 


ling Handbook 


0S/VS2 System Programming Library- Initialization and Tunin< 
Guide , GC28-0681 

0S/VS2 System Programming Library* Service Aids , GC28-0633 

0S/VS2 System Programming Library- Supervisor , GC28-0628 

0S/VS2 System Programming Library* System Generation 
Reference , GC26-3792 

IBM 3800 Printing Subsystem Programmer's Guide , GC26-3846 

IBM 3890 Document Processor Machine and Programming 
Description , GA24-3612 

OS Data Management Services and Macro Instructions for IBM 
1419/1275 , GC21-5006 

OS and OS/VS Prog r amming Support for t h e IBM 3505 Card 
Reader and IBM 3525 Card Punch , GC21-5097 

OS/VS IBM 3886 Optical Character Reader Model 1 Reference , 
GC24-5101 
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OS/VS Mass Storage System (MSS) Planning Guide , GC35-0011 


• OS/VS Mass Storage System (MSS) Services: General 
Information , GC35-0016 

• 0S/V5 Tape Labels , GC26-3795 

• QS/V52 MVS Utilities , GC26-3902 

In this manual; any references made to an IBM program product 
are not intended to state or imply that only IBM’s program 
product may be used; any functionally equivalent program may be 
used instead. This manual has references to the following IBM 
program products: 

• RACF-Resource Access Control Facility Program Number, 
5740-XXH 
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SUMMARY OF AMENDMENTS 


I DATA FACILITY DEVICE SUPPORT - 3375 SUPPORT 


The information to support the IBM 3375 is included. For more 
information* see Introduction to 3375 Direct Access Storage * 
GA26-1666. 

An entry for the 3375 has been added to the figures 
’’Direct-Access Storage Device Capacities” and "Direct-Access 
Device Overhead Formulas." 


0S/VS2 MVS DATA FACILITY DEVICE SUPPORT (5740-AM7) 


The information to support the IBM 3380 is included. For 
additional information* see Introduction to 3380 Direct Access 
Storage » GA26-1662. 

An entry for the 3380 has been added to the figures 
"Direct-Access Storage Device Capacities" and "Direct-Access 
Device Overhead Formulas." 


SERVICE CHANGES 


In "Basic Access Technique" the description of issuing the CHECK 
macro to check a READ or WRITE has successfully completed has 
been updated. 

"Retrieving a Sequential Data Set" has been updated concerning 
PURGE HALT I/O not being used to terminate outstanding I/O. 

In "Updating a Sequential Data Set” the description of 
overlapping I/O operations has been updated. 

In "Indexed Sequential Buffer and Work Area Requirements" the 
field HIRPD has been replaced by DS2HIRPR in the calculation of 
SMSW. 

In "Tape-to-disk update-direct data set" a qualification has 
been added concerning updating variable length records. 

"Routing Data through the system input and output streams" has 
been updated concerning SYSIH support for undefined records. 

In "Concatenating sequential and partitioned data sets" the 
maximum number of data sets has been updated. Also, the 
concatenation of unlike data sets with RPS considerations has 
been updated. 


OS/VS2 MVS 3800 ENHANCEMENTS 


Information to support the 3800 Enhancements is included in the 
following sections: 

• Exits to Special Processing Routines 

• SETPRT-Printer Setup 

• Routing Data Through the System Input and Output Streams 
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NEjj PROGRAMMING SUPPORT 


The information to support the IBM 3203 model 5 printer has been 
included. For additional information about the IBM 3203 Printer, 
see IBM 3203 Printer Component Description-and Operator's Guide , 
GA33-1515. 


Summary of Amendments 
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SERVICE CHANGES 


"Data Set Identification" has been updated concerning the 
cataloging of data set names. "Basic Access Techniques" has been 
updated concerning the overlapping of I/O requests with BDAM. 

A clarification has been added to "Chained Scheduling for I/O 
Operations." 

Another restriction when search direct cannot be used has been 
added to the section "Search Direct for Input Operations (Except 
5740-AM3)." 

The section "Search Direct for Input Operations (5740-AM3)" has 
been updated. 

The restriction for chained scheduling has been updated under 
"Determining the Length of a Record when using the BSAM READ 
macro." 

The section "FIND-Position to a Member" has been updated 
concerning the requirement to close and reopen a data set. 

A new section "Processing a Partitioned Data Set Residing on 
MSS" has been added to "Processing a Partitioned Data Set." 

The section "Indexed Sequential Buffer and Work Area 
Requirements" has been updated concerning a high level index 
greater than 65,535 bytes. 

The section "Specifying Space Requirements" has been updated 
concerning cylinder allocation. 

The section "Absolute Generation and Version Numbers" has been 
updated. 

The section "Relative Generation Numbers" has been updated and 
the section "Programming Considerations for Multiple Step Jobs" 
has been added. 


AUGUST, 1978 


The information contained in the System Library Supplement 
GC26-3892, 0S/VS2*MVS System Security Support Selectable Unit* 
Data Management Services-SU32 (5752-832) has been incorporated 
into this publication by this Technical Newsletter. 

A note has been added to the description of the DSORG operand 
concerning the creation of a direct data set. This is in "Data 
Set Organization (DSORG)." 

Under "Synchronous Error Routine Exit (SYNAD)," a note has been 
added concerning EROPT and a physical block of data. 

Under "Standard User Label Exit," the specification of labels by 
use of the LABEL= parameter in a DD statement has been updated 
and the defer input trailer label exit OC has been qualified. 

Under "User Totaling (BSAM and QSAM only)," a note has been 
added regarding the user totaling facility. 

Under "End of Volume Exit,” a note has been added concerning 
concatenated data sets with unlike attributes. 

Under "Opening and Closing a Data Set," the description of an 
indeterminate error has been updated. 

The description of RLSE under "CLOSE-Terminate Processing. of a 
Data Set" has been updated. 


Summary of Amendments 
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The default value for BUFNO when using Q5AM has been updated. 

A note has been added regarding the 4-byte buffer chain pointer 
under "FREEPOOL-Free a Buffer Pool.” 

In the section "Chained Scheduling for I/O Operations," a new 
item has been added to the chained scheduling restrictions. A 
restriction for chained scheduling with printer channel control 
tapes has also been added. 

Under "Updating a Sequential Data Set," a new rule has been 
added for Locate mode. 

Under "Find-Position to a Member," a note has been added 
regarding the search of a concatenated series of directories. 

In the section "Creating an Indexed Sequential Data Set," the 
paragraph concerning blocked records has been updated. 

A paragraph has been added about subtasking under the heading 
"Sharing a BISAM DCB between Related Tasks." 

The figure, "Directly Updating an Indexed Sequential Data Set" 
has been updated. 

In the section "Processing a Direct Data Set," a paragraph has 
been added concerning the DSORG parameter. 

Under "Adding or Updating Records on a Direct Data Set," a note 
has been added regarding extended search. 

Under "Concatenating Sequential and Partitioned Data Sets," a 
note has been added about spool data sets, and about data sets 
with unlike attributes. 

Under "Relative Generation Number," the description of skipping 
absolute generation numbers has been expanded. Also the 
paragraph concerning cataloging via JCL has been updated. The 
paragraph concerning cataloging of new generation data groups 
has been updated also. 


SEQUENTIAL ACCESS METHOD-EXTENDED (SAM-E) RELEASE 1 (5740-AM3) 


BPAM, BSAM, and QSAM support of direct-access storage devices 
(except BSAM MACRF=WL, create BDAM data set) has been modified 
to internally use the EXCPVR interface to IOS. This modification 
includes the functions of the chained scheduling option 
(0PTCD=C) and the search-direct option 0PTCD=Z). These options, 
therefore, need not be requested and are ignored if requested. 
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PART It INTRODUCTION TO DATA MANAGEMENT 


DATA SET CHARACTERISTICS 


The data management programs of the operating system help you 
achieve maximum efficiency in managing the mass of data 
associated with the many programs that are processed at your 
installation by providing systematic and effective means of 
organizing, identifying, storing, cataloging, and retrieving all 
data, including programs, processed by the operating system. 

Data set storage control, along with an extensive catalog 
system, makes it possible for you to retrieve data by symbolic 
name alone, without specifying device types and volume serial 
numbers. In freeing computer personnel from maintaining involved 
volume serial number inventory lists of stored data and 
programs, the catalog reduces manual intervention and the 
likelihood of human error. 

Data sets stored within the cataloging system can be classified 
according to installation needs. For example, a sales department 
could classify the data it uses by geographic area, by 
individual salesman, or by any other logical plan. 

The cataloging system also makes it possible for you to classify 
successive generations or updates of related data. These 
generations can be given an identical name and subsequently be 
referred to relative to the current generation. The system 
automatically maintains a list of the most recent generations. 

You can request data from a direct-access volume, a remote 
terminal, or a tape volume, and data organized sequentially or 
directly, in essentially the same way. In addition, data 
management provides: 

• Allocation of space on direct-access volumes. Flexibility 
and efficiency of direct-access devices are improved through 
greater use of available space. 

• Automatic retrieval of data sets by name alone. 

• Freedom to defer specifications such as buffer length, block 
size, and device type until a job is submitted for 
processing. This permits the creation of programs that are 
in many ways independent of their operating environment. 

Control of confidential data is provided by the data set 
security part of the operating system. You can prevent 
unauthorized access to payroll data, sales forecast data, and 
all other data sets that require special security attention. An 
individual can use a security-protected data set only after 
furnishing a predefined password. 

Input/output routines are provided to efficiently schedule and 
control the transfer of data between storage and input/output 
devices. Routines are available to: 

• Read data 

• Write data 

• Translate data from ASCII (American National Standard Code 
for Information Interchange) to EBCDIC (Extended Binary 
Coded Decimal Interchange Code) and back 

• Block and deblock records 

• Overlap reading, writing, and processing operations 
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• Read and verify volume and data set labels 

• Write data set labels 


• Automatically position and reposition volumes 

• Detect error conditions and correct them when possible 


• Provide exits to user-written error and label routines 

OS/VS data management programs also provide for a variety of 
methods for gaining access to a data set. The methods are based 
on data set organization and data access technique. 

OS/VS data sets can be organized in four ways: 

♦ S equential : Records are placed in physical rather than 
logical sequence. Given one record, the location of the next 
record is determined by its physical position in the data 
set. Sequential organization is used for all magnetic-tape 
devices, and may be selected for direct-access devices. 
Punched tape, punched cards, and printed output are 
sequentially organized. 


• Ind e xed Sequen t ial : Records are arranged in sequence, 
according to a key that is a part of every record, on the 
tracks of direct-access volume. An index or set of indexes 
maintained by the system gives the location of certain 
principal records. This permits direct as well as sequential 
access to any record. 

• Pirect : The records within the data set, which must be on a 
direct-access volume, may be organized in any manner you 
choose. All space allocated to the data set is available for 
data records. No space is required for indexes. You specify 
addresses by which records are stored and retrieved 

directly. 


• Partitioned : Independent groups of sequentially organized 
records, called members, are in direct-access storage. Each 
member has a simple name stored in a directory that is part 
of the data set and contains the location of the member's 
starting point. Partitioned data sets are generally used to 
store programs. As a result, they are often referred to as 
libraries. 


Requests for input/output operations on data sets through macro 
instructions employ two techniques: the technique for queued 
access and the technique for basic a c cess . Each technique is 
identified according to its treatment of buffering and 
synchronization of input and output with processing. The 
combination of an access technique and a given data set 
organization is called an access method . In choosing an access 
method for a data set, therefore, you must consider not only its 
organization, but also what you need to specify through macro 
instructions. Also, you may choose a data organization according 
to the access techniques and processing capabilities available. 


The code generated by the macro instructions for both techniques 
is optionally reenterable depending on the form in which 
parameters are expressed. 

In addition to the access methods provided by the operating 
system, an elementary access technique called execute channel 
progra m (EXCP) is also provided. To use this technique, you must 
establish your own system for organizing, storing, and 
retrieving data. Its primary advantage is the complete 
flexibility it allows you in using the computer directly. 


An important feature of data management is that much of the 
detailed information needed to store and retrieve data, such as 
device type, buffer processing technique, and format of output 
records need not be supplied until the job is ready to be 
executed. This device independence permits changes to those 
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specifications to be made without changes in the program. 
Therefore, you may design and test a program without knowing the 
exact input/output devices that will be used when it is 
executed. 

Device independence is a feature of both access techniques for 
processing a sequential data set. To some extent, you determine 
the degree of device independence achieved. Many useful 
device-dependent features are available as part of certain macro 
instructions, and achieving device independence requires some 
selectivity in their use. 


DATA SET IDENTIFICATION 

Any information that is a named, organized collection of 
logically related records can be classified as a data set. The 

information is not restricted to a specific type, purpose, or 

storage medium. A data set may be, for example, a source 
program, a library of macro instructions, or a file of data 
records used by a processing program. 

Whenever you indicate that a new data set is to be created and 
placed on auxiliary storage, you (or the operating system) must 
give the data set a name. The data set name identifies a group 

of records as a data set. All data sets recognized by name 

(referred to without volume identification) and all data sets 
residing on a given volume must be distinguished from one 
another by unique names. To assist in this, the system provides 
a means of qualifying data set names. 

A data set name is one simple name or a series of simple names 
joined together so that each represents a level of 
qualification. For example, the data set name DEPT58.SMITH.DATA3 
is composed of three simple names. Proceeding from the left, 
each simple name is a category within which the next simple name 
is a subcategory. The first name is referred to as the high 
level index, the last as the low level index. 

Each simple name consists of from 1 to 8 alphameric characters, 
the first of which must be alphabetic. The special character 
period (.) separates simple names from each other. Including all 
simple names and periods, the length of the data set name must 
not exceed 44 characters. Thus, a maximum of 22 simple names can 
make up a data set name. 

Data set names cannot be cataloged in a CVOL if a name is 
already cataloged whose levels match the highest or higher 
levels of the specified name. For example, the qualified name 
A.B.C.D cannot be cataloged if the name A.B. or A.B.C. is 
already cataloged, but the name A.B.C.D can be cataloged if AB.C 
or A.B.C.E is cataloged. 

To permit different executions of a program to process different 
data sets without program reassembly, the data set is not 
referred to by name in the processing program. When the program 
is executed, the data set name and other pertinent information 
(such as unit type and volume serial number) are specified in a 
job control statement called the data definition (DP ) statement. 
To gain access to the data set during processing, reference is 
made to a data control block (DCB) associated with the name of 
the DD statement. Space for a data control block, which 
specifies the particular data set to be used, is reserved by a 
DCB macro instruction when your program is assembled. 
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DATA SET STORAGE 


System/370 provides a variety of devices for collecting, 
storing, and distributing data. Despite the variety, the devices 
have many common characteristics. The generic term volume is 
used to refer to a standard unit of auxiliary storage. A volume 
may be a reel of magnetic tape, a disk pack, or a drum. 

Each data set stored on a volume has its name, location, 
organisation, and other control information stored in the data 
set label or volume table of contents (for direct-access volumes 
only). Thus, when the name of the data set and the volume on 
which it is stored are made known to the operating system, a 
complete description of the data set, including its location on 
the volume, can be retrieved. Then, the data itself can be 
retrieved, or new data added to the data set. 

Various groups of labels are used to identify magnetic-tape and 
direct-access volumes, as well as the data sets they contain. 
Magnetic-tape volumes can have standard or nonstandard labels, 
or they can be unlabeled. Direct-access volumes must use 
standard labels. Standard labels include a volume label, a data 
set label for each data set, and optional user labels. 

Keeping track of the volume on which a particular data set 
resides can be a burden and a source of error. To alleviate this 
problem, the system provides for automatic cataloging of data 
sets. The system can retrieve a cataloged data set if given only 
the name of the data set. If the name is qualified, each 
qualifier corresponds to one of the indexes in the catalog. For 
example, the system finds the data set DEPT58.SMITH.DATA3 by 
searching a master index to determine the location of the index 
name DEPT58, by searching that index to find the location of the 
index SMITH, and by searching that index for DATA3 to find the 
identification of the volume containing the data set. 

By use of the catalog, collections of data sets related by a 
common external name and the time sequence in which they were 
cataloged (their generation) can be identified; they are called 
generation data groups . For example, a data set name 
LAB.PAYROLL(0) refers to the most recent data set of the group; 
LAB.PAYROLL(-l) refers to the second most recent data set, etc. 
The same data set names can be used repeatedly with no 
requirement to keep track of the volume serial numbers used. 


Direct-Access Volumes 

Direct-access volumes are used to store executable programs, 
including the operating system itself. Direct-access storage is 
also used for data and for temporary working storage. One 
direct-access storage volume may be used for many different data 
sets, and space on it may be reallocated and reused. A volume 
table of contents (VTOC) is used to account for each data set 
and available space on the volume. 

Each direct-access volume is identified by a volume label, which 
is stored in track 0 of cylinder 0. You may specify up to seven 
additional labels, located after the standard volume label, for 
further identification. 

The VTOC is a data set consisting of data set control blocks 
(DSCBs) that describe the contents of the direct-access volume. 
The VTOC can contain seven kinds of DSCBs, each with a different 
purpose and a different format number. Q5/VS2 System Programming 
Library? Debugging Handbook describes the seven kinds of DSCBs, 
their purposes, and their formats. 

Each direct-access volume is initialized by a utility program 
before being used on the system. The initialization program 
generates the volume label and constructs the table of contents. 
For additional information on direct-access labels, see 
"Appendix A? Direct-Access Labels." 
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When a data set is to be stored on a direct-access volume, you 
must supply the operating system with the amount of space to be 
allocated to the data set, expressed in blocks, tracks, or 
cylinders. Space allocation can be independent of device type if 
the request is expressed in blocks. If the request is made in 
tracks or cylinders, you must be aware of such device 
considerations as cylinder capacity and track size. 




Magnetic-Tape Volumes 

Because data sets on magnetic-tape devices must be organized 
sequentially, the operating system does not require space 
allocation procedures comparable to those for direct-access 
devices. When a new data set is to be placed on a magnetic-tape 
volume, you must specify the data set sequence number if it is 
not the first data set on the reel. The operating system 
positions a volume with IBM standard labels, American National 
Standard labels, or no labels so that the data set can be read 
or written. If the data set has nonstandard labels, you must 
provide for volume positioning in your 

nonstandard-label-processing routines. All data sets stored on a 
given magnetic-tape volume must be recorded in the same density. 


When a data set is to be stored on an unlabeled tape volume and 
you have not specified a volume serial number, the system 
assigns a serial number to that volume and to any additional 
volumes required for the data set. Each such volume is assigned 
a serial number of the form Lxxxyy where xxx indicates the data 
set sequence number from IPL to IPL and yy indicates the volume 
sequence number for the data set. If you specify volume serial 
numbers for unlabeled volumes on which a data set is to be 
stored, the system assigns volume serial numbers to any 
additional volumes required. If data sets residing on unlabeled 
volumes are to be cataloged or passed, you should specify the 
volume serial numbers for the volumes required. This will 
prevent data sets residing on different volumes from being 
cataloged or passed under identical volume serial numbers. 
Retrieval of such data sets could result in unpredictable 
errors. 


Each data set and each data set label group on magnetic tape 
that is to be processed by the operating system must be followed 
by a tapemark. Tapemarks cannot exist within a data set. When 
the operating system is used to create a tape with standard 
labels or no labels, all tapemarks are automatically written. 

Two tapemarks are written after the last trailer label group on 
a volume to indicate the last data set on the volume. On an 
unlabeled volume, the two tapemarks are written after the last 
data set. 


When the operating system is used to create a tape data set with 
nonstandard labels, the delimiting tapemarks are not written. If 
the data set is to be retrieved by the operating system, those 
tapemarks must be written by your nonstandard-label-processing 
routine. Otherwise, tapemarks are not required after nonstandard 
labels since positioning of the tape volumes must be handled by 
installation routines. 

For more information on labels for magnetic-tape volumes, refer 
to OS/VS Tape Labels . 

The data on magnetic-tape volumes can be in either EBCDIC or 
ASCII. ASCII is a 7-bit code consisting of 128 characters. It 
permits data on magnetic tape to be transferred from one 
computer to another even though the two computers may be 
products of different manufacturers. 

Data management support of ASCII and of American National 
Standard tape labels is such that data management can translate 
records on input tapes in ASCII into EBCDIC for internal 
processing and translate the EBCDIC back into ASCII for output. 
Records on such input tapes may be sorted into ASCII collating 
sequence. 
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DATA SET RECORD FORMATS 


A data set is composed of a collection of records that normally 
have some logical relation to one another. The record is the 
basic unit of information used by a processing program. It might 
be a single character# all information resulting from a given 
business transaction# or measurements recorded at a given point 
in an experiment. Much data processing consists of reading# 
processing# and writing individual records. 


The process of grouping a number of records before writing them 
on a volume is referred to as blocking . A block is made up of 
the data between interrecord gaps (IRGs). Each block can consist 
of one or more records. Blocking conserves storage space on the 
volume because it reduces the number of IRGs in the data set. In 
many cases# blocking also increases processing efficiency by 
reducing the number of input/output operations required to 
process a data set. 


Records may be in one of four formats’ fixed-length (format-F)# 
variable-length for data in EBCDIC (format-V)# variable-length 
for data to be translated to or from ASCII (format~D)# or 
undefined-length (format-U). The main consideration in the 
selection of a record format is the nature of the data set 
itself. You must know the type of input your program will 
receive and the type of output it will produce. Selection of a 
record format is based on this knowledge# as well as on an 
understanding of the input/output devices that are used to 
contain the data set and the access method used to read and 
write the data records. The record format of a data set is 
indicated in the data control block according to specifications 
in the DCB macro instruction, the DD statement# or the data set 
label. 


For ASCII tapes# data can be in format-F# format-D# and format-U 
with the restrictions noted under "Fixed-Length Records# ASCII 
tapes#" "Variable-Length Records—Format D#" and 
"Undefined-Length Records.” When data management reads records 
from ASCII tapes# it translates the records into EBCDIC. When 
data management writes records onto ASCII tapes# it translates 
the records into ASCII. Because you use input records after they 
are translated and because output records are translated when 
you ask data management to write them, you work only with 
EBCDIC. Note: There is no minimum requirement for block size# 
however# if a data check occurs on a magnetic-tape device# any 
block shorter than 12 bytes in a Read operation or 18 bytes in a 
Write operation is treated as a noise record and lost. No check 
for noise is made unless a data check occurs. The sort/merge 
program does not accept physical blocks or logical records 
shorter than 18 bytes from any device. 


For the 3800 printer, the data in the record can contain two 
optional bytes. The optional control character used for carriage 
control# followed by an optional table reference character used 
for dynamically selecting a character arrangement table during 
printing. See the IBM 3800 Printing Subsystem Programmer's Guide 
for more information on the table reference' character. 


Fixed-Length Records 


The size of fixed-length (format-F) records# 
is constant for all records in the data set. 
records within a block is constant for every 
set# unless the data set contains truncated ( 
the data set contains unblocked format-F reco 
constitutes one block. 


shown in 
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The system automatically performs physical length 
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checking 
format-F 


6 


0S/VS2 Data Management Services Guide 



Format-F records are shown in Figure 14 on page 24. The optional 
control character (c), used for stacker selection or carriage 
control# may be included in each record to be printed or 
punched. 
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Figure 1. Fixed-Length Records 


FIXED-LENGTH RECORDS, STANDARD FORMAT: During creation of a 
sequential data set (to be processed by BSAM or QSAM) with 
fixed-length records, the RECFM subparameter of.the DCB macro 
instruction may specify a standard format (RECFM=FS or FBS). A 
standard-format data set must conform to the following 
specifications: 

• All records in the data set are format-F records. 

• No block except the last block is truncated. (With BSAM you 
must ensure that this specification is met.) 

• Every track except the last one contains the same number of 
blocks. 

• Every track except the last one is filled to capacity as 
determined by the track capacity formula established for the 
device. (These formulas are presented in Part 3 of this book 
under "Allocating Space on Direct-Access Volumes.") 

• The data set organization is physical-sequential. A member 
of a partitioned data set cannot be specified. 

A sequential data set with fixed-length records having a 
standard format can be read more efficiently than a data set 
that doesn't specify a standard format. This efficiency is 
possible because the system is able to determine the address of 
each record to be read because each track contains the same 
number of blocks. 

You should never extend a data set of this type (by coding 
DISP=M0D) if the last block is truncated, because the extension 
will cause the data set to contain a truncated block that isn't 
the last block. This type of data set on magnetic tape should 
not be read backward, because then the data set would begin with 
a truncated block. Consequently, you probably won't want to use 


Part 1: Introduction to Data Management 7 









this type of data set with magnetic tape. If you use one of the 
basic access techniques with this type of data set, you should 
not specify that the track overflow feature is to be used with 
the data set. 

Standard format should not be used to read records from a data 
set that was created using a RECFM other than standard since 
other record formats may not create the precise format required 
by standard. 

If at any time the characteristics of your data set are altered 
from the specifications described above, then the data set 
should no longer be processed with the standard format 
specification. 

FIXED-LENGTH RECORDS, ASCII TAPES: For ASCII tapes, format-F 
records are the same as described above, with two exceptions: 

• Control characters, if present, must be American National 
Standards Institute (ANSI) control characters. 

• Records or blocks of records can contain block prefixes. 

Figure 15 on page 29 shows the format of fixed-length records 
for ASCII tapes and where control characters and block prefixes 
go if they exist. 
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Figure 2. Fixed-Length Records for ASCII Tapes 


The block prefix can vary in length from 0 to 99 bytes but the 
length must be constant for the data set being processed. For 
blocked records, the block prefix precedes the first logical 
record. For unblocked records, the block prefix precedes each 
logical record. 

Using QSAM and BSAM to read records with,block prefixes requires 
that you specify the BUFOFF operand in the DCB. When using QSAM, 
you cannot read the block prefix on input. When using BSAM, you 
must account for the block prefix on both input and output. When 
using either QSAM or BSAM, you must account for the length of 
the block prefix in the BLKSIZE and BUFL operands of the DCB. 


* 
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When you use BSAM on output records* the operating system does 
not recognize a block prefix. Therefore* if you want a block 
prefix* it must be part of your record. Note that you cannot 
include block prefixes in QSAM output records. 

The block prefix con contain any data you want* but you must 
avoid using data types such as binary* packed decimal* and 
floating-point that cannot be translated into ASCII. 

For more information about control characters* refer to ’’Control 
Character” and to "Appendix B J Control Characters.” 


Variable-Length Records 

The variable-length record formats are format-V and format-D. 
Format-V records can be spanned; that is* records can be larger 
than the blocksize* as described below. Format-D records are 
used for ASCII tape data sets and cannot be spanned. Figure 3 
shows blocked and unblocked variable-length records without 
spanning. 


Block 


Blocked Records 


Unblocked Records 



Figure 3. Nonspanned* Variable-Length Records 


VARIABLE-LENGTH RECORDS—FORMAT V: Format V provides for 
variable-length records* variable-length record segments* each 
of which describes its own characteristics* and variable-length 
blocks of such records or record segments. Except when 
variable-length track overflow records are specified for volumes 
on devices with the rotational position sensing feature* the 
control program performs length checking of the block and uses 
the record or segment length information in blocking and 
deblocking. The first 4 bytes of each record* record segment* or 
block make up a descriptor word containing control information. 
You must allow for these additional 4 bytes in both your input 
and output buffers. 
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Block Descriptor Word*- A variable-length block consists of a 
block descriptor word (BDW) followed by one or more logical 
records or record segments. The block descriptor word is a 
4-byte field that describes the block. The first 2 bytes specify 
the block length ('JJL’)—4 bytes for the BDW plus the total 
length of all records or segments within the block. This length 
can be from 8 to 32,760 bytes or> when you are using WRITE with 
tape, from 18 to 32,760. The third and fourth bytes are reserved 
for future system use and must be 0. If the system does your 
blocking—that is, when you use the queued access technique—the 
operating system automatically provides the BDW when it writes 
the data set. If you do your own blocking—that is, when you use 
the basic access technique—you must supply the BDW. 

Record Descriptor Word: A variable-length logical record 
consists of record descriptor word (RDW) followed by the data. 
The record descriptor word is a 4-byte field describing the 
record. The first 2 bytes contain the length (’UL') of the 
logical record (including the 4-byte RDW). The length can be 
from 4 to 32,756. For information about processing a sequential 
data set, see "Data Format—Device Type Considerations." All 
bits of the third and fourth bytes must be 0, as other values 
are used for spanned records. For output, you must provide the 
RDW except in data mode for spanned records (described under 
"Buffer Control"). For output in data mode, you must provide the 
total data length in the physical record length field (DCBPRECL) 
of the DCB. For input, the operating system provides the RDW 
except in data mode. In data mode, the system passes the record 
length to your program in the logical record length field 
(DCBLRECL) of the DCB. The optional control character (c) may be 
specified as the fifth byte of each record and must be followed 
by at least one byte of data (the length in the RDW, in this 
case, would be six). The first byte of data is a table reference 
character if 0PTCD=J has been specified. The RDW, the optional 
control character, and the optional table reference character 
are not punched or printed. 

Spanned Variable-Length Records (Sequential Access Method): The 
spanning feature of the queued and basic sequential access 
methods enables you to create and process variable-length 
logical records that are larger than one physical block and/or 
to pack blocks with variable-length records by splitting the 
records into segments so that they can be written into more than 
one block, as shown in Figure 4 on page 11. 
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Figure 4. Spanned Variable-Length Records 


When spanning is specified for blocked records, the system tries 
to fill all blocks. For unblocked records, a record larger than 
blocksize is split and written in two or more blocks, each block 
containing only one record or record segment. Thus the blocksize 
may be set to the one that is best for a given device or 
processing situation. It is not restricted by the maximum record 
length of a data set. A record may, therefore, span several 
blocks, and may even span volumes. Note that a logical record 
spanning three or more volumes cannot be processed in update 
mode (described under "Buffer Control") by QSAM. A block can 
contain a combination of records and record segments, but not 
multiple segments of the same record. When records are added to 
or deleted from a data set, or when the data set is processed 
again with different blocksize or record-size parameters, the 
record segmenting will change. 

Considerations for Processing spanned Record Data Sets: When 
spanned records span volumes, reading errors may occur when 
using QSAM if a volume which begins with a middle or last 
segment is mounted first or if an FEOV macro instruction is 
issued followed by another GET. QSAM cannot begin reading from 
the middle of the record. The errors include duplicate records, 
program checks in the user’s program, and invalid input from the 
spanned record data set. 

When a spanned record data set is to be opened in UPDAT mode and 
QSAM is used, a record area must be provided by using the 
BUILDRCD macro instruction or by specifying BFTEK=A in the DCB. 
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If you issue the FEOV macro instruction when reading a data set 
that spans volumes, or if a spanned multivolume data set is 
opened to other than the first volume, make sure that each 
volume begins with the first (or only) segment of a logical 
record. Input routines cannot begin reading in the middle of a 
logical record. 

Segment Descriptor Word*- Each record segment consists of a 
segment descriptor word (SDW) followed by the data. The segment 
descriptor word, similar to the record descriptor word, is a 
4-byte field that describes the segment. The first 2 bytes 
contain the length (’H, 1 ) of the segment, including the 4-byte 
SDW. The length can be from 5 to 32,756 bytes or, when you are 
using WRITE with tape, from 18 to 32,756 bytes. The third byte 
of the SDW contains the segment control code, which specifies 
the relative position of the segment in the logical record. The 
segment control code is in the rightmost 2 bits of the byte. The 
segment control codes are shown in Figure 5. The remaining bits 
of the third byte and all of the fourth byte are reserved for 
future system use and must be 0. 
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The SDW for the first segment replaces the RDW for the record 
after the record has been segmented. You or the operating system 
can build the SDW, depending on which mode of processing is 
used. In the basic sequential access method, you must create and 
interpret the spanned records yourself. In the queued sequential 
access method move mode, complete logical records, including the 
RDW, are processed in your work area. GET consolidates segments 
into logical records and creates the RDW. PUT forms segments as 
required and creates the SDW for each segment. Data mode is 
similar to move mode, but allows reference only to the data 
portion of the logical record in your work area. The logical 
record length is passed to you through the DCBLRECL field of the 
data control block. In locate mode, both GET and PUT process one 
segment at a time. However, in locate mode, if you provide your 
own record area using the BUILDRCD macro instruction or if you 
ask the system to provide a record area by specifying BFTEK=A, 
then GET, PUT, and PUTX process one logical record at a time. 
(BFTEK=A or the BUILDRCD macro cannot be specified when logical 
records exceed 32,760 bytes. To process logical records that 
exceed 32,760 bytes, you must use locate mode and specify 
LRECL=X in your DCB macro.) 

A logical record spanning three or more volumes cannot be 
processed when the data set is opened for update. 

When unit-record devices are used with spanned records, the 
system assumes that unblocked records are being processed and 
the block size must be equivalent to the length of one print 
line or one card. Records that span blocks are written one 
segment at a time. 

SYSIN and SYSOUT Restrictions* Spanned variable-length records 
cannot be specified for a SYSIN data set. If you’re using QSAM 
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to process a SY50UT data set* move mode (see "Buffer Control") 
is more efficient than locate mode. 

Null Segments: A 1 in bit position 0 of the SDW indicates a null 
segment. A null segment means that there are no more segments in 
the block. Bits 1-7 of the SDW and the remainder of the block 
must be binary zeros. A null segment is not an 
end-of-logical-record delimiter. (You do not have to be 
concerned about null segments unless you have created a data set 
using null segments.) 

Spanned Variable-Length Records (Basic Direct Access Method): 

The spanning feature of the basic direct access method (BDAM) 
enables you to create and process variable-length unblocked 
logical records that are longer than one track. The feature also 
enables you to pack tracks with variable-length records by 
splitting the records into segments. These segments can then be 
written onto more than one track* as shown in Figure 6. 
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Figure 6. Spanned Variable-Length Records for BDAM Data Sets 


When you specify spanned* unblocked record format for the basic 
direct access method and when a complete logical record cannot 
fit on the track* the system tries to fill the track with a 
record segment. Thus the maximum record length of a data set is 
not restricted by block size. Furthermore* segmenting records 
allows a record to span several tracks* with each segment of the 
record on a different track. However* since the system does not 
allow a record to span volumes* all segments of a logical record 
in a direct data set are on the same volume. 
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VARIABLE-LENGTH RECORDS—FORMAT D: For ASCII tapes, 
variable-length records must be format-D records. Format-D 
records are the same as format-V records, except: 

• Control characters, if present, must be ANSI control 
characters. 

• Records or blocks of records can contain block prefixes. 

Figure 7 shows the format of variable-length records for ASCII 
tapes, where the record descriptor word (RDW) must go, and where 
block prefixes and control characters can go when they exist. 
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Figure 7. Variable-Length Records for ASCII Tapes 


To specify a block prefix, code the BUFOFF operand in the DCB 
macro. The block prefix can vary in length from 0 to 99 bytes 
but its length must remain constant for the data set being 
processed. For blocked records, the block prefix precedes the 
first logical record in each block. For unblocked records, the 
block prefix precedes each logical record. If the block prefix 
exists, it precedes the RDW. 

To specify that the block prefix is to be treated as a BDW by 
data management for format-D records on output, code BUF0FF=L as 
a DCB operand. Your block prefix must be 4 bytes long, and it 
must contain the length of the block, including the block 
prefix. The maximum length of a format D, BUFQFF=L block is 9999 
because the length (stated in binary by the user) is translated 
to a four-byte zoned decimal field on the ASCII tape when the 
tape is written, and is then converted back to a two-byte length 
field in binary followed by two bytes of zeros when the block is 
read. If you use QSAM to write records, data management fills in 
the block prefix for you. If you use BSAM to write records, you 
must fill in the block prefix yourself. If you are using chained 
scheduling to read blocked format-D records, coding 
BUFQFF= absolute expression in the DCB is not allowed. Instead, 
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BUFOFF=L is required* because the access method needs binary 
RDWs and valid end-of-block addresses to unblock the records. 

When using QSAM, you cannot read the block prefix on input. When 
using BSAM, you must account for the block prefix on both input 
and output. When using either QSAM or BSAM, you must account for 
the length of the block prefix in the BLKSIZE and BUFL operands. 

When you use BSAM on output records* the operating system does 
not recognize the block prefix. Therefore, if you want a block 
prefix* it must be part of your record. 

The block prefix can contain any data you want* but you must 
avoid using data types, such as binary* packed decimal, and, 
floating-point, that cannot be translated into ASCII. For 
format-D records, the only time the block prefix can contain 
binary data is when you have coded BUF0FF=L, which tells data 
management that the prefix is a BDW. Unlike the block prefix, 
the RDW must always be in binary. 

If you create variable-length records that are shorter than 18 
bytes, data management pads each one up to a length of 18 bytes 
when the records are written onto ASCII tape. The padding 
character used is the ASCII circumflex. 

For more information about control characters, refer to "Control 
Character" and to "Appendix B* Control Characters." 


Undefined-Length Records 

Format U permits processing of records that do not conform to 
the F or V format. As shown in Figure 8, each block is treated 
as a record; therefore, deblocking must be performed by your 
program. The optional control character may be used in the first 
byte of each record. Because the system does not perform length 
checking on format-U records, your program may be designed to 
read less than a complete block into virtual storage. 
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Figure 8. Undefined-Length Records 


For ASCII tapes, format-U records are the same as described 
above, with the two exceptions described for format-F records on 
ASCII tapes. 

Figure 9 shows the format of undefined-length records for ASCII 
tapes and where a control character and block prefix, if any, 
go. 

For format-U records, the user must specify the record length 
when issuing the WRITE, PUT, or PUTX macro instruction. No 
length checking is performed by the system, so no error 
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Figure 9. Undefined-Length Records for ASCII Tapes 


indication will be given if the specified length does not match 
the buffer si 2 e or physical record size. 

In update mode, you must issue a GET or READ macro before you 
issue a PUTX or WRITE macro to a data set on a direct-access 
device. If you change the record length when you issue the PUTX 
or WRITE macro, the record will be padded with zeros or 
truncated to match the length of the record received when the 
GET or READ macro was issued. No error indication will be given. 


Control Character 

You may specify in the DD statement, the DCB macro instruction, 
or the data set label that an optional control character is part 
of each record in the data set. The 1-byte character is used to 
indicate a carriage control channel when the data set is printed 
or a stacker bin when the data set is punched. Although the 
character is a part of the record in storage, it is never 
printed or punched. For that reason, buffer areas must be large 
enough to accommodate the character. If the immediate 
destination of the record is a device, such as disk, that does 
not recogni 2 e the control character, the system assumes that the 
control character is the first byte of the data portion of the 
record. If the destination of the record is a printer or punch 
and you have not indicated the presence of a control character, 
the system regards the control character as the first byte of 
data. A list of the control characters is in "Appendix B: 

Control Characters." 


3800 TABLE REFERENCE CHARACTER 


The 3800 Table Reference Character is a numeric character 
(0,1,2, or 3) corresponding to the order in which the character 
arrangement table names have been specified with the CHARS 
keyword. It is used for selection of a character arrangement 
table during printing. See IBM 3800 Printing Subsystem 
Programmer's Guide for more information on the table reference 
character. 
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DIRECT-ACCESS DEVICE CHARACTERISTICS 


Regardless of organization, data sets created using the 
operating system can be stored on a direct-access volume. Each 
block of data has a distinct location and a unique address, 
making it possible to locate any record without extensive 
searching. Thus, records can be stored and retrieved either 
directly or sequentially. 


Although direct-access devices differ in physical appearance, 
capacity, and speed, they are similar in data recording, data 
checking, data format, and programming. The recording surface of 
each volume is divided into many concentric tracks . The number 
of tracks and their capacity vary with the device. Each device 
has some type of access mechanism , containing read/write heads 
that transfer data as the recording surface rotates past them. 
Only one head at a time can transfer data. 


The logical arrangement of related tracks is vertical rather 
than horizontal. As shown in Figure 10, a cylinder of a 2316 
disk pack is composed of 20 tracks, one for each recording 
surface. Because there are 203 tracks per recording surface, 
there are 203 vertical cylinders of 20 tracks each. If a data 
set extends to more than 1 track, it is continued on the next 
track in the cylinder, not the next track on the same recording 
surface. 


00 Tracks 202 
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Comb-Type 
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Twenty Read-Write Heads 
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Figure 10. 2316 Disk Pack 
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TRACK FORMAT 


Information is recorded on all direct-access volumes in a 
standard format. In addition to device data, each track contains 
a track descriptor record ( capacity record or RO) and data 
records. 

As shown in Figure 11, there are two possible data record 
formats—count-data and count-key-data—only one of which can be 
used for a particular data set. 
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Figure 11. Direct-Access Volume Track Formats 


In addition to device data, the count area contains 8 bytes that 
identify the location of the record by cylinder, head, and 
record numbers, its key length (0 if no keys are used), and its 
data length. 

If the records are written with keys, the key area (1 to 255 
bytes) contains a record key that specifies the data record by 
part number, account number, sequence number, or some other 
identifier. In some cases, records are written with keys so that 
they can be located quickly. 


TRACK ADDRESSING 

Two types of addresses can be used to store and retrieve data on 
a direct-access volume: actual addresses and relative addresses. 
The only advantage of using actual addresses is the elimination 
of time required to convert from relative to actual addresses 
and vice versa. When sequentially processing a multipie-volume 
data set, you can refer only to records of the current volume. 

ACTUAL ADDRESSES 2 When the system returns the actual address of 
a record on a direct-access volume to your program, it is in the 
form MBBCCHHR, where 2 

M 

is a 1-byte binary number specifying the relative location 
of an entry in a data extent block (DEB). The data extent 
block is created by the system when the data set is opened. 
Each extent entry describes a set of consecutive tracks 
allocated ,for the data set. 

BBCCHH 

is three 2-byte binary numbers specifying the cell (bin), 
cylinder, and head number for the record (its track 
address). The cylinder and head numbers are recorded in the 
count area for each record. 
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R 

is a 1-byte binary number specifying the relative block 
number on the track. The block number is also recorded in 
the count area. 

If you use actual addresses in your program, the data set must 
be treated as unmovable. 

RELATIVE ADDRESSES* Two kinds of relative addresses can be used 
to refer to records in a direct-access data set* relative block 
addresses and relative track addresses. 

The relative block address is a 3-byte binary number that 
indicates the position of the block relative to the first block 
of the data set. Allocation of noncontinuous sets of blocks does 
not affect the number. The first block of a data set always has 
a relative block address of 0. 

The relative track address has the form TTR, where* 

TT 

is a 2-byte binary number specifying the position of the 
track relative to the first track allocated for the data 
set. The TT for the first track is 0. Allocation of 
noncontinuous sets of tracks does not affect the number. 

R 

is a 1-byte binary number specifying the number of the 
block relative to the first block on the track TT. The R 
value for the first block of data on a track is 1. 


TRACK OVERFLOW 


If the record overflow feature is available for the 
direct-access device being used, you can reduce the amount of 
unused space on the volume by specifying the track overflow 
option in the DD statement or the DCB macro instruction 
associated with the data set. If the option is used, a block 

that does not fit on the track is partially written on that 

track and continued on the next track. (The track onto which the 

record is continued must be physically next and must be part of 

the same extent as the track that holds the first part of the 
record.) Each segment (the portion written on one track) of an 
overflow block has a count area. The data length field in the 
count area specifies the length of that segment only. If the 
block is written with a key, there is only one key area for the 
block. It is written with the first segment. If the track 
overflow option is not used, blocks are not split between 
tracks. 


WRITE-VALIDITY-CHECK OPTION 

You can specify the write-validitv-check option in either the DD 
statement or the DCB macro instruction. After a record is 
transferred from main to secondary storage, the system reads the 
stored record (without data transfer) and, by testing for a data 
check from the I/O device, verifies that the record was written 
correctly. This verification requires an additional revolution 
of the device for each record that was written. Standard error 
recovery procedures are initiated if an error condition is 
detected. 
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THE DATA CONTROL BLOCK 


You must describe the character!stics of a data set, the volume 
on which it resides, and its processing requirements before 
processing can begin. During execution, the descriptive 
information is made available to the operating system in the 
data control block (DCB) . A DCB is required for each data set 
and is created in a processing program by a DCB macro 
instruction. 

Primary sources of information to be placed in the data control 
block are a DCB macro instruction, a data definition (DD) 
statement, and a data set label. In addition, you can provide or 
modify some of the information during execution by storing the 
pertinent data in the appropriate field of the data control 
block. The specifications needed for input/output operations are 
supplied during the initialization procedures of the OPEN macro 
instruction. Therefore, the pertinent data can be provided when 
your job is to be executed rather than when you write your 
program (see Figure 12). 



Figure 12. Completing the Data Control Block 


When the OPEN macro instruction is executed, the Open routine* 

• Completes the data control block 

• Loads all necessary access method routines not already in 
virtual storage 

• Initializes data sets by reading or writing labels and 
control information 

• Constructs the necessary system control blocks 

Information from a DD statement is stored in the job file 
control block (JFCB) by the operating system. When the job is to 
be executed, the JFCB is made available to the open routine. The 
data control block is filled in with information from the DCB 
macro instruction, the JFCB, or an existing data set label. If 
more than one source specifies information for a particular 
field, only one source is used. A DD statement takes precedence 
over a data set label, and a DCB macro instruction over both. 
However, you can modify most data control block fields either 
before the data set is opened or when the operating system 
returns control to your program (at the data control block open 
exit). Some fields can be modified during processing. 
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Figure 13 illustrates the process and the sequence of filling in 
the data control block from various sources. The primary source 
is your program# that is# the DCB macro instruction. In general# 
you should use only those DCB parameters that are needed to 
ensure correct processing. The other parameters can be filled in 
when your program is to be executed. When a direct-access data 
set is opened (or a magnetic tape with standard labels is opened 
for INPUT# RDBACK# or INOUT), any field in the JFCB not 
completed by a DD statement is filled in from the data set label 
(if one exists). When opening a magnetic tape for output# the 
tape label is assumed not to exist or to apply to the current 
data set unless you specify DISP=M0D and a volume serial number 
in the volume parameter of the DD statement. Any field not 
completed in the DCB is filled in from the JFCB. Fields in the 
DCB can then be completed or modified by your own DCB exit 
routine. Then all DCB fields are unconditionally merged into 
corresponding JFCB fields if your data set is opened for output. 
This is done by specifying OUTPUT# OUTIN# EXTEND# or OUTINX in 
the OPEN macro instruction. The DSORG field is not merged unless 
this field contains zeros in the JFCB. If your data set is 
opened for input (INPUT# INOUT# RDBACK# or UPDAT is specified in 
the OPEN macro instruction)# the DCB fields are not merged 
unless the corresponding JFCB fields contain zeros. 



Figure 13. Sources and Sequence of Operations for Completing 
the Data Control Block 


When the data set is closed# the data control block is restored 
to the condition it had before the data set was opened (the 
buffer pool is not freed). The open and close routines also use 
the updated JFCB to write the data set labels for output data 
sets. If the data set is not closed when your program 
terminates# the operating system will close it automatically. 
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DATA SET DESCRIPTION 

For each data set you are going to process* there must be a 
corresponding DCB and DD statement. The characteristics of the 
data set and device-dependent information can be supplied by 
either source. In addition* the DD statement must supply data 
set identification* device characteristics* space allocation 
requests* and related information as specified in 0S/VS2 JCL . 

You establish the logical connection between a DCB and a DD 
statement by specifying the name of the DD statement in the 
DDNAME field of the DCB macro instruction* or by completing the 
field yourself before opening the data set. 

Once the data set characteristics have been specified in the DCB 
macro instruction* they can be changed only by modification of 
the DCB during execution. The fields of the DCB discussed below 
are common to most data organizations and access techniques. 

DATA SET ORGANIZATION (DSORG): specifies the organization of the 
data set as physical sequential (PS)* indexed sequential (IS)* 
partitioned (PO)* or direct (DA). If the data set contains 
absolute rather than relative addresses* you must mark it as 
unmovable by adding a U to the DSORG parameter (for example* by 
coding DS0RG=PSU). You must specify the data set organization in 
the DCB macro instruction. When creating or processing an 
indexed sequential organization data set or creating a direct 
data set* you must also specify DSORG in the DD statement. When 
creating a direct data set* the DSORG in the DCB macro must 
specify PS or PSU and the DD statement must specify DA or DAU. 

RECORD FORMAT (RECFM): specifies the characteristics of the 
records in the data set as fixed-length (F)* variable-length 
(V)* or undefined-length (U). Blocked records are specified as 
FB or VB. You may also specify the records as fixed-length 
standard by using FS or FBS. You can request track overflow for 
records other than standard format by adding a T to the RECFM 
parameter (for example* by coding FBT). 

RECORD LENGTH (LRECL): specifies the length* in bytes* of each 
record in the data set. If the records are of variable length* 
the maximum record length must be specified. For input* the 
field should be omitted for format-U records. 

BLOCKSIZE (BLKSIZE): specifies the maximum length* in bytes* of 
a block. If the records are of format F» the blocksize must be 
an integral multiple of the record length except for SYSOUT data 
sets. (See "Routing Data Through the System Input and Output 
Streams" in Part 3 of this book.) If the records are of format 
V* the blocksize specified must be the maximum blocksize. If 
records are unblocked* the blocksize must be 4 bytes greater 
than the record length (LRECL). When spanned variable-length 
records are specified* the blocksize is independent of the 
record length. 

KEY LENGTH (KEYLEN): specifies the length (0-255) in bytes of an 
optional key which precedes each block on a direct-access 
device. The value of KEYLEN is not included in BLKSIZE or LRECL 
but must be included in BUFL if buffer length is specified. 

Thus, BUFL=KEYLEN+BLKSIZE. 

Each of the data set description fields of the data control 
block, except as noted for data set organization* can be 
specified when your job is to be executed. In addition* data set 
identification and disposition* as well as device 
characteristics* can be specified at that time. The parameters 
of the DD statement discussed below are common to most data set 
organizations and devices. 

DATA DEFINITION NAME (DDNAME): is the name of the DD statement 
and connects the DD statement to the data control block that 
specifies the same DDNAME, 

DATA SET NAME (D5NAME): specifies the name of a newly defined 
data set* or refers to a previously defined data set. 







22 0S/VS2 Data Management Services Guide 



DATA CONTROL BLOCK (DCB): provides* by means of subparameters* 
information to be used to complete those fields "of the data 
control block that were not specified in the DCB macro 
instruction. This parameter cannot be used to modify a data 
control block. 

CHANNEL SEPARATION AND AFFINITY (SEP/AFF): requests that 
specified data sets use different channels during input/output 
operations. 

INPUT/OUTPUT DEVICE (UNIT): specifies the number and type of I/O 
devices to be allocated for use by the data set. 

SPACE ALLOCATION (SPACE): designates the amount of space on a 
direct-access volume that should be allocated for the data set. 
Unused space can be released when your job is finished. 

VOLUME IDENTIFICATION (VOLUME): identifies the particular volume 
or volumes* or the number of volumes* to be assigned to the data 
set* or the volumes on which existing data sets reside. 

DATA SET LABEL (LABEL): indicates the type and contents of the 
label or labels associated with the data set. The operating 
system verifies standard labels. Standard labels include those 
specified in the DD statement as SL (standard labels), SUL 
(standard user labels), AL (American National Standard labels), 
and AUL (American National Standard user labels). Nonstandard 
labels (NSL) can be specified only if your installation has 
incorporated into the operating system routines to write and 
process nonstandard labels. 

DATA SET DISPOSITION (DISP): describes the status of a data set 
and indicates what is to be done with it at the end of the job 
step. 


PROCESSING PROGRAM DESCRIPTION 

The operating system requires several types of processing 
information to ensure proper control of your input/output 
operations. The forms of macro instructions in the program* 
buffering requirements* and the addresses of your special 
processing routines must be specified during either the assembly 
or the execution of your program. The DCB parameters specifying 
buffer requirements are discussed in "Buffer Acquisition and 
Control." 

Because macro instructions are expanded during the assembly of 
your program* you must supply the macro instruction forms that 
are to be used in processing each data set in the associated DCB 
macro instruction. You can supply buffering requirements and 
related information in the DCB macro instruction, the DD 
statement, or by storing the pertinent data in the appropriate 
field of the data control block before the end of your DCB exit 
routine. If the addresses of special processing routines are 
omitted from the DCB macro instruction* you must complete them 
in the DCB before opening the data set. 


Macro Instruction Form (MACRF) 

The MACRF parameter of the DCB macro instruction specifies not 
only the macro instructions used in your program, but also the 
processing mode as discussed in the section "Buffer Control." 
The organisation of your data set* the macro instruction form* 
and the processing mode determine which of the data access 
routines will be used during execution. 
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Exits to special Processing Routines 


The DCB macro instruction can be used to identify the location 
of • 

• A routine that performs end-of-data procedures 

• A routine that supplements the operating system’s error 
recovery routine 

• A list that contains addresses of special exit routines 

The exit addresses can be specified in the DCB macro instruction 
or you can complete the DCB fields before opening the data set. 
Figure 14 summarizes the exits that you can specify either 
explicitly in the DCB, or implicitly by specifying the address 
of an exit list in the DCB. 


Exit Routine 

When Available 

Where Specified 

End-of-Data-Set 

When no more sequential 
records or blocks are 
available 

EODAD operand 


Error Analysis 

After an uncorrectable 
input/output error 

SYNAD operand 


Standard User Label 

When opening, closing. 

EXLST operand 

and 

(physical sequential 
or direct organization) 

or reaching the end of 
a data set, and when 
changing volumes 

exit list 


DCB Open 

When opening a data set 

EXLST operand 
exit list 

and 

JFCBE 

When opening a data set 
for the 3800 

EXLST operand 
exit list 

and 

End-of-Volume 

When changing volumes 

EXLST operand 
exit list 

and 

Block Count 

After unequal block count 
comparison by end-of-volume 
routine 

EXLST operand 
exit list 

and 

FCB Image 

When opening a data set or 
issuing a SETPRT macro 

EXLST operand 
exit list 

and 

DCB ABEND 

When an ABEND condition 
occurs in Open, Close, or 
end-of-volume routine. 

EXLST operand 
exit list 

and 


Figure 14. Data Management Exit Routines 


END-OF-DATA-SET EXIT ROUTINE ( EODAD )‘ The EODAD parameter of the 
DCB macro instruction specifies the address of your end-of-data 
routine, which may perform any final processing on an input data 
set. This routine is entered when an FEOV macro is issued or 
when a CHECK or GET macro is issued and there are no more 
records or blocks to be retrieved. (On a READ request, this 
routine is entered when you issue a CHECK macro instruction to 
check for completion of the read operation. For a B5AM data set 
that is opened for UPDAT, this routine is entered at the end of 
each volume. This allows you to issue WRITE macros before an 
FEOV macro is issued.) 

The EODAD routine is not a subroutine, but rather a continuation 
of the routine which issued the CHECK, GET, or FEOV macro 
instruction. Once in your EODAD routine, you can continue normal 
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processing, such as reposition and resume processing of the data 
set, close the data set, or process another data set. 


For BSAM, you must first reposition the data set that reached 
end-of-data if you wish to issue a BSP, READ, or WRITE macro 
instruction. You can reposition your data set by issuing a CLOSE 
TYPE=T macro instruction. If a READ macro is issued before the 
data set is repositioned, unpredictable results will occur. 

For BPAM, you may reposition the data set by issuing a FIND or 
POINT macro instruction. (CLOSE TYPE=T with BPAM results in a no 
operation performed.) 

For QISAM, you can continue processing the input data set that 
reached end-of-data by first issuing an ESETL macro to end the 
sequential retrieval, then issuing a SETL macro to set the lower 
limit of sequential retrieval. You can then issue GET macros to 
the data set. 

Your task will be abnormally terminated under either of the 
following conditions 5 

• No exit routine is provided. 

• A GET macro instruction is issued in the EODAD routine to 
the DCB which caused this routine to be entered (unless the 
access method is QISAM). 

When control is passed to the EODAD routine, the registers 
contain the following information 5 


Register Contents 

0-1 Reserved 

2-13 Contents before execution of CHECK, GET, or FEOV macro 

instruction 

14 Address of the instruction after the last issued GET, 

CHECK, or FEOV macro instruction 

15 Reserved 

SYNCHRONOUS ERROR ROUTINE EXIT CSYNAD ) 5 The SYNAD parameter of 
the DCB macro instruction specifies the address of an error 
routine that is to be given control when an input/output error 
occurs. This routine can be used to analyse exceptional 
conditions or uncorrectable errors. The block being read or 
written can be accepted or skipped, or processing can be 
terminated. 

If an input/output error occurs during data transmission, 
standard error recovery procedures, provided by the operating 
system, attempt to correct the error before returning control to 
your program. An uncorrectable error usually causes an abnormal 
termination of the task. However, if you specify in the DCB 
macro instruction the address of an error analysis routine 
(called a SYNAD routine), the routine is given control in the 
event of an uncorrectable error. 

You can write a SYNAD routine to determine the cause and type of 
error that occurred by examining 5 

• The contents of the general registers 

• The data event control block (discussed in Part 2 under 
"Basic Access Technique") 

• The exceptional condition code 

• The standard status and sense indicators 
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You can use the SYNADAF macro instruction to perforin this 
analysis automatically. This macro instruction produces an error 
message that can be printed by a subsequent PUT or WRITE macro 
instruction. 

After completing the analysis, you can return control to the 
operating system or close the data set. If you close the data 
set, note that you may not use the temporary close (CLOSE 
TYPE=T) option in the SYNAD routine. To continue processing the 
same data set, you must first return control to the control 
program by a RETURN macro instruction. The control program then 
transfers control to your processing program, subject to the 
conditions described below. In no case should you attempt to 
reread or rewrite the record, because the system has already 
attempted to recover from the error. 

When you are using GET and PUT to process a sequential data set, 
the operating system provides three automatic error options 
(EROPT) to be used if there is no SYNAD routine or if you want 
to return control to your program from the SYNAD routine: 

• ACC accept the erroneous block 

• 5KP skip the erroneous block 

• ABE abnormally terminate the task 

These options are applicable only to data errors, as control 
errors result in abnormal termination of the task. Data errors 
affect only the validity of a block of data. Control errors 
affect information or operations necessary for continued 
processing of the data set. These options are not applicable to 
output errors, except output errors on the printer. If the EROPT 
and SYNAD fields are not completed, ABE is assumed. 

Since EROPT applies to a physical block of data, and not to a 
logical record, use of SKP or ACC may result in incorrect 
assembly of spanned records. 

When you use READ and WRITE macro instructions, errors are 
detected when you issue a CHECK macro instruction. If you are 
processing a direct or sequential data set and you return to the 
control program from your SYNAD routine, the operating system 
assumes that you have accepted the bad record. If you are 
creating a direct data set and you return to the control program 
from your SYNAD routine, your task is abnormally terminated. In 
the case of processing a direct data set, the return should be 
made to the control program via register 14 in order to make a 
control block (the IOB) available for reuse in a subsequent READ 
or WRITE macro instruction. 

For a detailed description of the register contents upon entry 
to your SYNAD routine, refer to the tables in 0S/VS2 MVS Data 
Manage m ent Macro Instructions . The tables there describe 
register contents for programs using QISAM, BISAM, BDAM, BPAM, 
BSAM, and QSAM. 

Your SYNAD routine can end by branching to another routine in 
your program, such as a routine that closes the data set. It can 
also end by returning control to the control program, which then 
returns control to the next sequential instruction (after the 
macro) in your program. If your routine returns control, the 
conventions for saving and restoring register contents are as 
follows! 

• The SYNAD routine must preserve the contents of registers 13 
and 14. If required by the logic of your program, the 
routine must also preserve the contents of registers 2 
through 12. Upon return to your program, the contents of 
registers 2 through 12 will be the same as upon return to 
the control program from the SYNAD routine. 
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• The SYNAD routine must not use the save area whose address 
is in register 13, because this area is used by the control 
program. If the routine saves and restores register 
contents, it must provide its own save area. 

• If the SYNAD routine calls another routine or issues 
supervisor or data management macro instructions, it must 
provide its own save area or issue a SYNADAF macro 
instruction. The SYNADAF macro instruction provides a save 
area for its own use, and then makes this area available to 
the SYNAD routine. Such a save area must be removed from the 
save area chain by a SYNADRLS macro instruction before 
control is returned to the control program. 


When you use QSAM to read and translate papei—tape characters, 
your SYNAD routine receives control when you request the record 
preceding the record in error. Before giving control to your 
SYNAD routine, the system translates the requested record into 
your buffer. 


For example, suppose that you are using QSAM to read and 
translate a papei—tape data set and that you have specified, in 
your DCB, SYNAD=(address) and ER0PT=ACC. Suppose also that the 
third record of the data set has a parity error. When you issue 
a GET request for the second record, the system translates that 
record into your buffer and, as a result of the error in the 
third record, passes control to your SYNAD routine. Because you 
specified the accept option, the system returns control to your 
program after your SYNAD error analysis routine completes its 
processing. When you issue a GET request for the third record, 
all characters other than the erroneous one are translated into 
your buffer; the erroneous character is moved, in normal 
sequence, into your buffer without translation. 


If the error analysis routine receives control from the Close 
routine when indexed sequential data sets are being created (the 
DCB is opened for QISAM load mode), bit 3 of the IOBFLAGS field 
in the load mode buffer control table (IOBBCT) is set to one. 

The DCBWKPT6 field in the DCB contains an address of a list of 
work area pointers (ISLVPTRS). The pointer to the IOBBCT is at 
offset 8 in this list as shown in the following diagram*- 



If the error analysis routine receives control from the Close 
routine when indexed sequential data sets are being processed 
using QISAM scan mode, bit 2 of the DCB field DCBEXCD2 is set to 
one. 

EXIT LIST (EXLST): The EXLST parameter of the DCB macro 
instruction specifies the address of a list that contains the 
addresses of special processing routines, a forms control buffer 
(FCB) image, or a user totaling area. An exit list must be 
created if user label, data control block, end-of-volume, block 
count, JFCBE, or DCB ABEND exits are used, or if a PDAB macro or 
FCB image is defined in the processing program. 
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The exit list is constructed of 4-byte entries that must be 
aligned on fullword boundaries. Each exit list entry is 
identified by a code in the high-order byte# and the address of 
the routine* image* or area is specified in the 3 low-order 
bytes. Codes and addresses for the exit list entries are shown 
in Figure 15. 

You can activate or deactivate any entry in the list by placing 
the required code in the high-order byte. Care must be taken* 
however, not to destroy the last entry indication. The operating 
system routines scan the list from top to bottom, and the first 
active entry found with the proper code is selected. 

You can shorten the list during execution by setting the 
high-order bit to 1* and extend it by setting the high-order bit 
to 0. 

When control is passed to an exit routine* the registers contain 
the following information* 


Register Contents 

0 Variable; see exit routine description. 


1 The three* low-order bytes contain the address of DCB 

currently being processed* except when usei—label 
exits (X T 01’- f 04’ ), user totaling exit (X'OA')* or DCB 
ABEND exit (X f ll’) is taken* when register 1 contains 
the address of a parameter list. The contents of the 
parameter list are described in each exit routine 
description. 


2-13 Contents before execution of the macro instruction. 


14 


Return address (must not be altered by the exit 
routine). 


15 


Address of exit routine entry point. 


The conventions for saving and restoring register contents are 
as follows : 

• The exit routine must preserve the contents of register 14. 
It need not preserve the contents of other registers. The 
control program restores the contents of registers 2-13 
before returning control to your program. 

• The exit routine must not use the save area whose address is 
in register 13* because this area is used by the control 
program. If the exit routine calls another routine or issues 
supervisor or .data management macro instructions* it must 
provide the address of a new save area in register 13. 

Standard User Label Exit: When you create a data set with 
physical sequential or direct organization, you can provide 
routines to create your own data set labels. You can also 
provide routines to verify these labels when you use the data 
set as input. Each label is 80 characters long with the first 4 
characters UHL 1,UHL2*...*UHL8 for a header label or 
UTL1 *UTL2*...*UTL8 for a trailer label. User labels are not 
allowed on indexed sequential data sets. 
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Entry Type 

Hexadecimal 

Code 

3-byte Address—Purpose 

Inactive entry 


00 

Ignore the entry; it is not active. 

Input header label exit 

01 

Process a user input header label. 

Output header label 

exi t 

02 

Create a user output header label. 

Input trailer label 

exi t 

03 

Process a user input trailer label. 

Output trailer label 

exit 

04 

Create a user output trailer label. 

Data control block exit 

05 

Take a data control block exit. 

End-of-volume exit 


06 

Take an end-of-volume exit. 

JFCB exit 


07 

JFCB address for RDJFCB and 

OPEN TYPE=J SVCs. 



08-09 

Reserved for future use 

User totaling area 


0A 

Address of beginning of user's 
totaling area. 

Block count exit 


0B 

Take a block-count-unequal exit. 

Defer input trailer 
label 


OC 

Defer processing of a user 

input trailer label 

from end-of-data until closing. 

Defer nonstandard 
input trailer label 


0D 

Defer processing a nonstandard input 
trailer labelmagnetic tape unit from 
end-of-data until closing 
(no exit routine address). 



0E-0F 

Reserved for future use 

FCB image 


10 

Define an FCB image. 

DCB ABEND exit 


11 

Examine the ABEND condition and select 
one of several options. 

QSAM parallel input 


12 

Address of the PDAB for which this DCB 
is a member. 



13-14 

Reserved for future use 

JFCBE exit 


15 

Take an exit during open to allow user 
to examine JCL=specified setup 
requirements for a 3800 printer. 



16-7 F 

Reserved for future use 

Last entry 


80 

Treat this entry as last 


entry in list. 

This code can be specified with 
any of the above but must always be 
specified with the last entry. 

Figure 15. Format and Contents of an Exit List 


The physical location of the labels on the data set depends on 
the data set organization. For direct (BDAM) data sets, user 
labels are placed on a separate user label track in the first 
volume. User label exits are taken only during execution of the 
open and close routines. Thus you may create or examine up to 
eight user header labels only during execution of open and up to 
eight trailer labels only during execution of close. Since the 
trailer labels are on the same track as the header labels, the 
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first volume 
is closed. 

of the data 

set must 

be mounted 

when 

the 

data set 


For physical 

sequential 

(BSAM or 

QSAM) data 

sets, 

you 

may create 

\ 


or examine up to eight header labels and eight trailer labels on 
each volume of the data set. For ASCII tape data sets, you may 
create an unlimited number of user header and trailer labels. 

The user label exits are taken during open, close, and 
end-of-volume processing. 

To create or verify labels, you must specify the addresses of 
your label exit routines in an exit list as shown in Figure 15. 
Thus you may have separate routines for creating or verifying 
header and trailer label groups. Care must be taken if a 
magnetic tape is read backward, since the trailer label group is 
processed as header labels and the header label group is 
processed as trailer labels. 

When your routine receives control, the contents of register 
are unpredictable. Register 1 contains the address of a 
parameter list. The contents of registers 2-13 are the same as 
when the macro instruction was issued. However, if your program 
does not issue the CLOSE macro instruction, or abnormally 
terminates before issuing CLOSE, the CLOSE macro instruction 
will be issued by the control program, with control-program 
information in these registers. 

The parameter list pointed to by register 1 is a 16-byte area 
aligned on a fullword boundary. Figure 16 shows the contents of 
the area. 




Figure 16. Parameter List Passed to User Label Exit Routine 
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When a user label exit routine receives control after an 
uncorrectable I/O error has occurred, the third entry of the 
parameter list contains the address of the standard status 
information. The error flag (high-order byte of the third entry 
in the parameter list) is set as follows: 

bit 0=1: Uncorrectable I/O error 

bit 1=1: Error occurred during writing of updated label 
bits 2-7: Reserved 

The fourth entry in the parameter list is the address of the 
user totaling image area. This image area is the entry in the 
user totaling save area that corresponds to the last record 
physically written on the volume. The image area is discussed 
further under "User Totaling." 

Each routine must create or verify one label of a header or 
trailer label group, place a return code in register 15, and 
return control to the operating system. The operating system 
responds to the decimal return code as shown in Figure 17. 

You can create user labels only for data sets on magnetic-tape 
volumes with IBM standard labels or American National Standard 
labels and for data sets on direct-access volumes. When you 
specify both user labels and IBM standard labels in a DD 
statement by specifying LABEL=(,SUL) and there is an active 
entry in the exit list, a label exit is always taken. Thus, a 
label exit is taken even when an input data set does not contain 
user labels, or when no user label track has been allocated for 
writing labels on a direct-access volume. In either case, the 
appropriate exit routine is entered with the buffer area address 
parameter set to 0. On return from the exit routine, normal 
processing is resumed? no return code is necessary. 

Label exits are not taken for system output (5YS0UT) data sets, 
or for data sets on volumes that do not have standard labels. 

For other data sets, exits are taken as follows: 

• When an input data set is opened, the input header label 
exit 01 is taken. If the data set is on tape, being opened 
for RDBACK, user trailer labels will be processed. 
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Routine Type 


Return Cods 


System Response 


Input header 0 

or 

trailer label 


4 


8 1 


12 x 


Output header 0 

or trailer label 


Normal processing is resumed. 

If there are any remaining 
labels in the label group, they 
are ignored. 

The next user label is read into 
the label buffer area and control 
is returned to the exit routine. 

If there are no more labels in 
the label group, normal processing 
is resumed. 

The label is written from the 
label buffer area and normal 
processing is resumed. 

The label is written from the 
label area, the next label is read 
into the label buffer area, and 
control is returned to the label 
processing routine. 

If there are no more labels, 
processing is resumed. 

Normal processing is resumed; 
no label is written from the label 
buffer area. 


4 User label is written 

from the label buffer area. 

Normal processing is resumed. 

8 User label is written from the label 

buffer area. 

If fewer than eight labels have been 
created, control is returned to the 
exit routine, which then creates 
the next label. 

If eight labels have been created, 
normal processing is resumed. 


x Your input label routines can return these codes only when 
you are processing a physical sequential data set opened 
for UPDAT or a direct data set opened for OUTPUT or UPDAT. 

These return codes allow you to verify the existing labels, update 
them if necessary, then request that the system write 
the updated labels. 


Figure 17. System Response to a User Label Exit Routine Return Code 
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• When an output data set is opened, the output header label 
exit 2 is taken. However, if the data set already exists and 
DI5P=M0D is coded in the DD statement, the input trailer 
label exit 03 is taken to process any existing trailer 
labels. If the input trailer label exit 03 does not exist, 
then the deferred input trailer label exit 0C is taken if it 
exists; otherwise, no label exit is taken. For tape, these 
trailer labels will be overwritten by the new output data or 
by EOV or close processing when writing new standard trailer 
labels. For direct-access devices, these trailer labels will 
still exist unless rewritten by EOV or close processing in 
an output trailer label exit. 

• When an input data set reaches end-of-volume, the input 
trailer label exit 03 is taken. If the data set is on tape 
opened for RDBACK, header labels will be processed. The 
input trailer label exit 03 is not taken if you issue an 
FEOV macro instruction. If a defer input trailer label exit 
0C is present, and an input trailer label exit 03 is not 
present, the 0C exit is taken. After switching volumes, the 
input header label exit 01 is taken. If the data set is on 
tape opened for RDBACK, trailer labels will be processed. 

• When an output data set reaches end-of-volume, the output 
trailer label exit 04 is taken. After switching volumes, 
output header label exit 02 is taken. 

• When an input data set reaches end-of-data, the input 
trailer label exit 03 is taken before the EODAD exit, unless 
the DCB exit list contains a defer input trailer label exit 
0C. 

• When an input data set is closed, no exit is taken unless 
the data set was previously read to end-of-data and the 
defer input trailer label exit 0C is present. If so, the 
defer input trailer label exit 0C is taken to process 
trailer labels, or if the tape is opened for RDBACK, header 
labels. 

• When an output data set is closed, the output trailer label 
exit 4 is taken. 

To process records in reverse order, a data set on magnetic tape 
can be read backward. When you read backward, header label exits 
are taken to process trailer labels, and trailer label exits are 
taken to process header labels. The system presents labels from 
a label group in ascending order by label number, which is the 
order in which the labels were created. If necessary, an exit 
routine can determine label type (UHL or UTL) and number by 
examining the first four characters of each label. Tapes with 
IBM standard labels and direct-access devices can have as many 
as eight user labels. Tapes with American National Standard 
labels can have unlimited user labels. 

If an uncorrectable error occurs during reading or writing of a 
user label, the system passes control to the appropriate exit 
routine with the third word of the parameter list flagged and 
pointing to status information. 

After an input error, the exit routine must return control with 
an appropriate return code (0 or 4). No return code is required 
after an output error. If an output error occurs while the 
system is opening a data set, the data set is not opened (DCB is 
flagged) and control is returned to your program. If an output 
error occurs at any other time, the system attempts to resume 
normal processing. 

User Totaling CBSAM and QSAM only): When creating or processing 
a data set with user labels, you may develop control totals for 
each volume of the data set and store this information in your 
user labels. For example, control total that was accumulated as 
the data set was created can be stored in your user label and 
later compared with a total accumulated during processing of the 
volume. User totaling assists you by synchroni zi ng the control 
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data you create with records physically written on a volume. For 
an output data set without user labels* you can also develop a 
control total that will be available to your end-of-volume 
routine. 

To request user totaling* you must specify OPTCD=T in the DCB 
macro instruction or in the DCB parameter of the DD statement. 

The area in which you accumulate the control data (the user 
totaling area) must be identified to the control program by an 
entry of hexadecimal OA in the DCB exit list. 0PTCD=T cannot be 
specified for SYSIN or SYSOUT data sets. 

The user totaling area, an area in storage that you provide, 
must begin on a halfword boundary and be large enough to contain 
your accumulated data plus a 2-byte length field. The length 
field must be the first 2 bytes of the area and specify the 
length of the entire area. A data set for which you have 
specified user totaling (0PTCD=T) will not be opened if either 
the totaling area length or the address in the exit list is 0, 
or if there is no X'OA’ entry in the exit list. 

The control program establishes a user totaling save area, in 
which the control program preserves an image of your totaling 
area, when an I/O operation is scheduled. When the output user 
label exits are taken, the address of the save area entry (user 
totaling image area) corresponding to the last record physically 
written on a volume is passed to you in the fourth entry of the 
user label parameter list. This parameter list is described in 
the section "Standard User Label Exit." When an end-of-volume 
exit is taken for an output data set and user totaling has been 
specified, the address of the user totaling image area is in 
register 0. 

When using user totaling for an output data set, that is, when 
creating the data set, you must update your control data in your 
totaling area before issuing a PUT or a WRITE macro instruction. 
The control program places an image of your totaling area in the 
user totaling save area when an I/O operation is scheduled. A 
pointer to the save area entry (user totaling image area) 
corresponding to the last record physically written on the 
volume, is passed to you in your label processing routine. Thus 
you can include the control total in your user labels. When 
subsequently using this data set for input, you can accumulate 
the same information as you read each record and compare this 
total with the one previously stored in the user trailer label. 
If you have stored the total from the preceding volume in the 
user header label of the current volume, you can process each 
volume of a multi volume data set independently and still 
maintain this system of control. 

When variable-length records are specified with the totaling 
facility for user labels, special considerations are necessary. 
Since the control program determines whether a variable-length 
record will fit in a buffer after a PUT or a WRITE has been 
issued, the total you have accumulated may include one more 
record than is actually written on the volume. In the case of 
variable-length spanned records, the accumulated total will 
include the control data from the volume-spanning record 
although only a segment of the record is on that volume. 

However, when you process such a data set, the volume-spanning 
record or the first record on the next volume will not be 
available to you until after the volume switch and user label 
processing are completed. Thus the totaling information in the 
user label may not agree with that developed during processing 
of the volume. 

One way you can resolve this situation is to maintain, when you 
are creating a data set, control data pertaining to each of the 
last two records and include both totals in your user labels. 
Then the total related to the last complete record on the volume 
and the volume-spanning record or the first record on the next 
volume would be available to your user label routines. During 
subsequent processing of the data set, your user label routines 
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can determine if there is agreement between the generated 
information and one of the two totals previously saved. 

When the totaling facility for user labels is selected with DA5D 
devices and secondary space is specified* the total accumulated 
may be one less than the actual written. 

Data Control Block open Exit: You can specify in an exit list 
the address of a routine that completes or modifies a DOB and 
does any additional processing required before the data set is 
completely open. The routine is entered during the opening 
process after the JFCB has been used to supply information for 
the DCB. The routine can determine data set characteristics by 
examining fields completed from the data set labels. When your 
DCB exit routine receives control, the three, low-order bytes of 
register 1 will contain the address of the DCB currently being 
processed. 

As with label processing routines, register 14's contents must 
be preserved and restored if any macro instructions are used in 
the routine. Control is returned to the operating system by a 
RETURN macro instruction; no return code is required. 

This exit is mutually exclusive with the JFCBE exit. If you need 
both the JFCBE and data control block open exits, you must use 
the JFCBE exit to pass control to your routines. 

QSAM Parallel Input Exit: A request for parallel input 
processing is indicated by including the address of a parallel 
data access block (PDAB) in the DCB exit list. The address must 
be on a fullword boundary with the first byte of the entry 
containing X f 12’ or, if it is the last entry, X’92’. For more 
information on parallel input processing, see ’’Parallel Input 
Processing (QSAM Only).’’ 

JFCBE Exit: JCL-specified setup requirements for the 3800 
printer cause a JFCB extension (JFCBE) to be created to reflect 
those specifications. A JFCBE exits if BURST, MODIFY, CHARS, 
FLASH, or any copy group is coded on the DD statement. The JFCBE 
exit can be used to examine or modify those specifications in 
the JFCBE. You can provide a JFCBE exit routine to examine or 
modify those specifications. The address of the routine should 
be placed in an exit list. The device allocated does not have to 
be a 3800. This exit is taken during open processing and is 
mutually exclusive with the data control block exit. If you need 
both the JFCBE and data control block exits, you must use the 
JFCBE exit to pass control to your routines. 

With 3800 Enhancements, when you issue the SETPRT macro to a 
SYSOUT data set the JFCBE is further updated from the 
information in the SETPRT parameter list. 

When control is passed to your exit routine, the contents of 
register and 1 will be: 


Register contents 


0 If a JFCBE exists, this register will point to an area 

in unprotected storage into which a copy of the JFCBE 
has been placed. If a JFCBE does not exist, this 
register will be zero. 

1 The address of the DCB being processed. 


Registers 2-15 will contain the standard user exit contents. 


The area pointed to by register 0 will also contain the 4-byte 
FCB identification which is obtained from the JFCB. The FCB 
identification is placed in the four bytes following the 
176-byte JFCBE, If the FCB operand was not coded on the DD 
statement, this FCB field will be binary zeros. 
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If your copy of the JFCBE is modified during an exit routine, 
you should indicate this fact by turning on bit JFCBEOPN (X’80* 
in JFCBFLAG) in the JFCBE copy. On return to open, this bit 
indicates whether the system copy is to be updated. The 4-byte 
FOB identification in your area will be used to update the JFCB 
regardless of the bit setting. Checkpoint/restart also 
interrogates this bit to determine which version of the JFCBE 
will be used at restart time. If this bit is not on, the JFCBE 
generated by the restart JCL will be used. 

End-of-Volume Exit : You can specify in an exit list the address 
of a routine that is entered when end-of-volume is reached in 
processing of a physical sequential data set. 

When you concatenate data sets with unlike attributes, no EOV 
exits are taken. 

When the end-of-volume routine is entered, register 0 contains 0 
unless user totaling was specified. If you specified user 
totaling in the DCB macro instruction (by coding 0PTCD=T) or in 
the DD statement for an output data set, register 0 contains the 
address of the user totaling image area. The routine is entered 
after a new volume has been mounted and all necessary label 
processing has been completed. If the volume is a reel of 
magnetic tape, the tape is positioned after the tapemark that 
precedes the beginning of the data. 

You can use the end-of-volume (EOV) exit routine to take a 
checkpoint by issuing the CHKPT macro instruction, which is 
discussed in QS/VS2 Checkpoint/Restart ; specifications for the 
CHKPT macro are also included in 0S/VS2 MVS Data Management 
Macro Instructions . If a checkpointed job step terminates 
abnormally, it can be restarted from the EOV checkpoint. When 
the job step is restarted, the volume is mounted and positioned 
as upon entry to the routine. Restart becomes impossible if 
changes are made to the link pack area (LPA) library between the 
time the checkpoint is taken and the time the job step is 
restarted. When the step is restarted, pointers to end-of-volume 
modules must be the same as when the checkpoint was taken. 

The end-of-volume exit routine returns control in the same 
manner as the data control block exit routine. Register 14's 
contents must be preserved and restored if any macro 
instructions are used in the routine. Control is returned to the 
operating system by a RETURN macro instruction; no return code 
is required. 

Block Count Exit: You can specify in an exit list the address of 
a routine that will allow you to abnormally terminate the task 
or continue processing when the end-of-volume routine finds an 
unequal block count condition. When you are using standard 
labeled input tapes, the block count in the trailer label is 
compared by the end-of-volume routine with the block count in 
the DCB. The count in the trailer label reflects the number of 
blocks written when the data set was created. The number of 
blocks read when the tape is used as input is contained in the 
DCBBLKCT field of the DCB. 

The routine is entered during end-of-volume processing. The 
trailer label block count is passed in register 0. You may gain 
access to the count field in the DCB by using the address passed 
in register 1 plus the proper displacement, as given in 0S/VS2 
System Programming Library/: Debugging Handbook . If the block 
count in the DCB differs from that in the trailer label when no 
exit routine is provided, the task is abnormally terminated. The 
routine must terminate with a RETURN macro instruction and a 
return code that indicates what action is to be taken by the 
operating system, as shown in Figure 18. As with other exit 
routines, register 14's contents must be saved and restored if 
any macro instructions are used. 
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Return Code System Action 

0 The task is to be abnormally terminated. 

4 Normal processing is to be resumed. 

Figure 18, System Response to Block Count Exit Return Code 


Defer Nonstandard Input Trailer Label Exit*- In an exit list, you 
can specify a code that indicates that you want to defer 
nonstandard input trailer label processing from end-of-data 
until the data set is closed. The address portion of the entry 
is not used by the operating system. 

An end-of-volume condition exists in several situations. Two 
examples are: (1) when the system reads a filemark or tapemark 
at the end of a volume of a multi volume data set but that volume 
is not the last, and (2) when the system reads a filemark or 
tapemark at the end of a data set. The first situation is 
referred to here as an end-of-volume condition, and the second 
as an end-of-data condition, although it, too, can occur at the 
end of a volume. 

For an end-of-volume (EOV) condition, the EOV routine passes 
control to your nonstandard input trailer label routine, whether 
or not this exit code is specified. For an end-of-data condition 
when this exit code is specified, the EOV routine does not pass 
control to your nonstandard input trailer label routine. 

Instead, the close routine passes control to your end-of-data 
routine. 

FCB Image Exit: You can specify in an exit list the address of a 
forms control buffer (FCB) image. This FCB image can be loaded 
into the forms control buffer of the printer control unit. The 
FCB controls the movement of forms in printers that do not use a 
carriage control tape. 

Multiple exit list entries in the exit list can*define FCBs. The 
open and SETPRT routines search the exit list for requested FCBs 
before searching SYS1.IMAGELIB. 

The first 4 bytes of the FCB image contain the image identifier. 
To load the FCB, this image identifier is specified in the FCB 
parameter of the DD statement, by the SETPRT macro instruction, 
or by the system operator in response to message IEC127D or 
IEC129D. 

For a 3211 the image identifier is followed by the FCB image 

described in QS/VS2 _Syste m Programming Library: Data Management . 

For a 3800, see IBM 3800 Printing Subsystem Programmers Guide . 

You can use an exit list to define an FCB image only when 
writing to an online printer. Figure 19 illustrates one way the 
exit list can be used to define an FCB image. 
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EXLIST 


FCBIMG 

* 16 line 


//ddname 

/X 


DCB 

..,EXLST = EXL1ST 


DS* 

OF 


DC 

X'10' 

Flag code for FCB image 

DC 

AL 3(FCBIMG) 

Address of FCB image 

DC 

X*80000000' 

End of EXLST and a null 

DC 

CL4'IMG1' 

FCB identifier 

DC 

X'00' 

FCB is not a default 

DC 

AL1(67 ) 

Length of FCB 

DC 

X' 90 ' 

Offset print line 


character positions to the right 


DC 

X’00' 

Spacing is 

6 lines 

per inch 

DC 

5X' 0 0 ’ 

L i nes 

2-6 


no channel codes 


DC 

X'01' 

Line 

7 channel 1 




DC 

6X ' 0 0 ' 

Lines 

8-13 

no channel codes 


DC 

X' 02' 

Line 

(or 

L 

i n e s) 

14 

channel 

2 

DC 

5X ' 0 0 * 

L i ne 

(or 

L 

ines) 

15 

-19 no channel 

DC 

X' 0 3 ' 

Line 

(or 

L 

i nes) 

20 

channel 

3 

DC 

9X' 0 0 * 

Line 

(or 

L 

ines) 

21 

-29 no channel 

DC 

X' 04 1 

Line 

(or 

L 

ines) 

30 

channel 

4 

DC 

19X'00 ' 

Line 

(or 

L 

ines) 

31 

-49 no channel 

DC 

X 1 05' 

Line 

(or 

L 

ines) 

50 

channel 

5 

DC 

X' 06' 

Line 

(or 

L 

i nes) 

51 

channel 

6 

DC 

X' 07' 

Line 

Cor 

L 

i nes) 

52 

channel 

7 

DC 

X' 08' 

Line 

(or 

L 

i nes) 

53 

channel 

8 

DC 

X' 0 9 ' 

Line 

(or 

L 

ines) 

54 

channel 

9 

DC 

X ’ 0 A' 

Line 

(or 

L 

i nes) 

55 

channel 

10 

DC 

X' 0B' 

Line 

(or 

L 

i nes) 

56 

channel 

11 

DC 

X'OC’ 

L i ne 

(or 

L 

ines) 

57 

channel 

12 

DC 

8X' 0 0 f 

Line 

(or 

L 

ines) 

58 

-65 no channel 

DC 

X'10' 

End of FCB 

i mage 



END 









DD 

UNIT=3211, 

FCB=(IMG1,VERIFY) 







codes 

codes 

codes 


codes 


Figure 19. Defining an FCB Image for a 3211 


DCB ABEND Exits The DCB ABEND exit is provided to give you some 
options regarding the action you want the system to take when a 
condition arises that may result in abnormal termination of your 
task. This exit can be taken any time an ABEND condition arises 
during the process of opening, closing, or handling an 
end-of-volume condition for a DCB associated with your task. 

When an ABEND condition arises, a write-to-programmer message 
about the ABEND is issued and your DCB ABEND exit is given 
control, provided there is an active DCB ABEND exit routine 
address in the DCB being processed. If STOW called the 
end-of-volume routines to get secondary space to write an 
end-of-file mark for a partitioned data set, or if the DCB being 
processed is for an indexed sequential data set, the DCB ABEND 
exit routine will not be given control if an ABEND condition 
occurs. The contents of the registers when your exit routine is 
entered are the same as for other DCB exit list routines except 
that the three, low-order bytes of register 1 contain the 
address of the parameter list described in Figure 20. Your ABEND 
exit routine can choose one of four options 5 

• to immediately terminate your task, 

• to delay the ABEND until all of the DCBs in the same OPEN or 
CLOSE macro instruction are opened or closed, 

• to ignore the ABEND condition and continue processing 
without making reference to the DCB on which the ABEND 
condition was encountered, or 

• to try to recover from the error. 
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f 

V 



Bit 

Meaning 

0-3 

Reserved for Future Use 

4 

OK to Recover 

5 

OK to Ignore 

6 

OK to Delay 

7 

Reserved for Future Use 


Displacement 

0 

4 

8 

12 


System Completion Code* 

_X 

Return Code 

Option Mask 

DCB Address 

Open/Close/End-of-Volume Work Area Address 

00 

Recovery Work Area Address 


*ln the first 12 bits. 

Figure 20. Parameter List Passed to DCB ABEND Exit Routine 


Not all of these options are available for each ABEND condition. 
Your DCB ABEND exit routine must determine which option is 
available by examining the contents of the option mask byte 
(byte 3) of the parameter list. The address of the parameter 
list is passed in register 1. Figure 20 shows the contents of 
the parameter list and the possible settings of the option mask 
when your routine receives control. All information in the 
parameter list is in binary. 

When your DCB ABEND exit routine returns control to the system 
control program (this can be done using the RETURN macro 
instruction)/ the option mask byte should contain the setting 
that specifies the action you want to take. These actions and 
the corresponding settings of the option mask byte are: 
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Bit setting Action 


0 abnormally terminate the task immediately 

4 ignore the ABEND condition 

8 delay the ABEND until the other DCBs being 

processed concurrently are opened or closed 

12 make an attempt to recover 

You must inspect bits 4, 5, and 6 of the option mask byte (byte 
3 of the parameter list) to determine which options are 
available. If a bit is set to 1, the corresponding option is 
available. Indicate your choice by inserting the appropriate 
value in byte 3 of the parameter list* overlaying the bits you 
inspected. If you use a value that specifies an option that is 
not available, the ABEND is issued immediately. 

If the contents of the option mask are 0, you must request an 
immediate ABEND by leaving the value of 0 in the option mask 
unchanged. 

If bit 5 of the option mask is set to 1, you can ignore the 
ABEND by placing a decimal value of 4 in byte 3 of the parameter 
list. Processing on the current DCB stops. If you subsequently 
attempt to use this DCB, the results are unpredictable. If you 
ignore an error in end-of-volume, the data set will be closed 
before control is returned to your program at the point which 
caused the end-of-volume condition (unless the end-of-volume 
routines were called by the close routines). If the 
end-of-volume routines were called by the close routines, an 
ABEND macro will be issued even though the ignore option was 
selected. 

If bit 6 of the option mask is set to 1, you can delay the ABEND 
by placing a decimal value of 8 in byte 3 of the parameter list. 
All other DCBs waiting for open or close processing will be 
processed before the ABEND is issued. For end-of-volume, 
however, you can't delay the ABEND because the end-of-volume 
routine never has more than one DCB to process. 

If bit 4 of the option mask is set to 1, you can attempt to 
recover. Place a decimal value of 12 in byte 3 of the parameter 
list and provide information for the recovery attempt. Figure 21 
lists the ABEND conditions for which recovery can be attempted. 
For ABEND conditions which can be ignored or delayed, see OS/VS 
Message Library^ VS2 System Messages . 
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System 

completion 

Code 

Return 

coda 

Description of Error 


213 

04 

DSCB was not found on volume specified. 

237 

04 

Block count in DCB does not agree 
count in trailer label. 

with block 

413 

18 

Data set was opened for input and 
serial number was specified. 

no volume 

613 

08 

I/O error occurred during reading 

of tape label. 


oc 

Invalid tape label was read. 



10 

I/O error occurred during writing 

of tape label. 


14 

I/O error occurred during writing 
tapemark following header labels. 

of 

713 

04 

A data set on magnetic tape was opened 


for INOUT# but the volume contained a data set 
whose expiration date had not been reached and the 
operator denied permission. 

717 10 I/O error occurred during reading of trailer 

label 1 to update block count in DCB. 

813 04 Data set name on header label does not match 

data set name on DD statement. 

Figure 21. Conditions for which Recovery Can Be Attempted 


Recovery Requirements! For the recovery attempt# you should 
supply a recovery work area (see Figure 22) with a new volume 
serial number for each volume associated with an error. If no 
new volumes are supplied# recovery will be attempted with the 
existing volumes# but the likelihood of successful recovery is 
greatly reduced. 
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Figure 22. Recovery Work Area 


If you request recovery for system completion code 213# return 
code 04# you must indicate in your job control language (JCL) 
that the volumes are nonsharable by specifying unit affinity# 
deferred mounting# or more volumes than units for the data set. 

If you request recovery for system completion code 237# return 
code 04# you don't need to supply new volumes or a work area. 

The condition that caused the ABEND is the disagreement between 
the block count in the DCB and that in the trailer label. This 
disagreement is ignored to permit recovery. 

If you request recovery for system completion code 717# return 
code 10, you don't need to supply new volumes or a work area. 

The ABEND is caused by an I/O error during updating of the DCB 
block count. To permit recovery# the block count is not updated. 
Consequently# an abnormal termination with system completion 
code 237# return code 04# may result when you try to read from 
the tape after recovery. You may attempt recovery from the ABEND 
with system completion code 237# return code 04# as explained in 
the preceding paragraph. 

System completion codes and their associated return codes are 
described in OS/VS Message Library* VS2 System Codes . 
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The work area that you supply for the recovery attempt must 
begin on a halfword boundary and can contain the information 
described in Figure 22. Place a pointer to the work area in the 
last 3 bytes of the parameter list pointed to by register 1 and 
described in Figure 20. 

If you acquire the storage for the work area by using the 
GETMAIN macro instruction, you can request that it be freed by a 
FREEMAIN macro instruction after all information has been 
extracted from it. Set the high-order bit of the option byte in 
the work area to 1 and place the number of the subpool from 
which the work area was requested in byte 3 of the recovery work 
area. 

Only one recovery attempt per data set is allowed during open, 
close, or end-of-volume processing. If a recovery attempt is 
unsuccessful, you may not request another recovery. The second 
time through the exit routine you may request only one of the 
other options (if allowed )’ issue the ABEND immediately, ignore 
the ABEND, or delay the ABEND. If at any time you select an 
option that is not allowed, the ABEND is issued immediately. 

Note that if recovery is successful, you still receive an ABEND 
message on your listing. This message refers to the ABEND that 
would have been issued if the recovery had not been successful. 


MODIFYING THE DATA CONTROL BLOCK 

You can complete or modify the DCB during execution of your 
program. You can also determine data set characteristics from 
information supplied by the data set labels. Changes or 
additions can be made before opening of the data set, after 
closing it, during the DCB exit routine, or while the data set 
is open. Naturally, any information must be supplied before it 
is needed. 

Because each DCB does not have a symbolic name for each field, a 
DCBD macro instruction must be used to supply the symbolic 
names. By loading a base register with the address of the DCB to 
be processed, you can refer to any field symbolically. 

The DCBD macro instruction generates a dummy control section 
(DSECT) named IHADCB. The name of each field consists of DCB 
followed by the first five letters of the keyword operand that 
represents the field in the DCB macro instruction. For example, 
the field reserved for blocksize is referred to as DCBBLKSI. For 
the names of other fields, including names of bits, see QS/VS2 
System Programming Library: Debugging Handbook . 

The attributes of each DCB field are defined in the dummy 
control section. Because each field in the DCB is not 
necessarily aligned on a fullword boundary, care must be taken 
when storing or moving data into the field. The length attribute 
and the alignment of each field can be determined from an 
assembly listing of the DCBD macro instruction. 

The DCBD macro instruction can be coded once to describe all 
DCBs even though their fields differ because of differences in 
data set organization and access technique. It must not be coded 
more than once for a single assembly. If it is coded before the 
end of a control section, it must be followed by a CSECT or 
DSECT statement to resume the original control section. 

CHANGING AN ADDRESS IN THE DATA CONTROL BLOCK: Figure 23 
illustrates how you can modify a field in the data control 
block. The DCBD macro instruction defines the symbolic name of 
each field. 
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OPEN 

(TEXTDCB,INOUT) 

EOFEXIT 

CLOSE 

(TEXTDCB,REREAD),TYPE=T 


LA 

10,TEXTDCB 


USING 

IHADCB,10 


MVC 

DCBSYNAD+1(3),=AL3(OUTERROR) 


B 

OUTPUT 

INERROR 

STM 

14,12,SYNADSA+12 

OUTERROR 

STM 

14,12,SYNADSA+12 

TEXTDCB 

DCB 

DSORG=PS,MACRF=(R,W),DDNAME=TEXTTAPE, 
E0DAD=E0FEXIT,SYNAD=INERROR 


DCBD 

DS0RG=PS 

Figure 23. 

Modifying 

a Field in the Data Control Block 


The data set defined by the data control block TEXTDCB is opened 
for use as both an input and an output data set. When its use as 
an input data set is completed, the EODAD routine closes the 
data set temporarily to reposition the volume for output. The 
EODAD routine then uses the dummy control section IHADCB to 
change the error exit address (SYNAD) from INERROR to OUTERROR. 

The EODAD routine loads the address TEXTDCB into register 10, 
which it uses as a base register for IHADCB. It then moves the 
address OUTERROR into the DCBSYNAD field of the DCB. This field 
is a fullword, but contains information that must not be 
disturbed in the high-order byte. For this reason, care must be 
taken to change only the 3 low-order bytes of the field. 

All unused address fields in the DCB, except DCBEXLST, are set 
to 1 during the DCB macro expansion. Many system routines 
interpret a value of 1 in an address field to mean "no address 
specified." If you modify an address field and then want to 
reset it to "no address specified," you should set it to a value 
of 1. 


SHARING A DATA SET 

There are two conditions under which a data set on a 
direct-access device can be shared by two or more tasks* 

• Two or more DCBs are opened and used concurrently by the 
tasks to refer to the same, shared data set (multiple DCBs). 

• Only one DCB is opened and used concurrently by multiple 
tasks in a single job step (a single, shared DCB). 

Job control language (JCL)•statements and macro instructions are 
provided in the operating system to help you to ensure the 
integrity of the data sets you wish to share among the tasks 
that process them. Figures 24 and 25 show which JCL and macro 
instructions you should use, depending on the access method your 
task is using and mode of access (input, output, or update). 

Figure 24 describes the macro instructions, JCL, and processing 
procedures you should use if more than one DCB has been opened 
to the shared data set. The DCBs can be used by tasks in the 
same or different job steps. 
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MULTIPLE DCBS 


Access Mode 

Access Method 

BSAM,BPAM, 
BDAM Create 

QSAM 

BDAM 

QISAM 

BISAM 

Input 

DISP = SHR 

DISP = SHR 

DISP - SHR 

DISP = SHR 

DISP = SHR 

Output 

No Facility 

No Faci1ity 

DISP = SHR 

Ho Facility 

DISP = SHR 
and ENQ on 
Data Set 

Update 

DISP = SHR 
and ENQ on 
Block 

DISP = SHR 
and Guarantee 
Discrete 
Blocks 

DISP = SHR 
and ENQ on 
Block 

DISP = SHR 
and ENQ on 
Data Set and 
Guarantee 

Discrete 
Blocks 

DISP = SHR 
and ENQ on 
Data Set and 
Guarantee 

Discrete 
Blocks 


DISP=SHR: 

Each job step sharing an existing data set must code SHR as the 
subparameter of the DISP parameter on the DD statement for the shared data 
set to allow the steps to execute concurrently. For additional information 
about ensuring data set integrity, see Q5/VS2 JCL . If the tasks are in the 
same job step, DISP=SHR is not required. 

Ho Facility: 

There are no facilities in the operating system for sharing a data set 
under these conditions. 

ENQ on Data Set: 

In addition to coding DISP=SHR on the DD statement for the data set that 
is to be shared, each task must issue ENQ and DEQ macro instructions 
naming the data set as resource for which exclusive control is required. 
The ENQ must be issued before the GET (READ); the DEQ macro should be 
issued after the PUTX or CHECK macro that concludes the operation. See 
0S/VS2 Supervisor Services and Macro Instructions for additional 
information on the use of ENQ and DEQ macro instructions. 

Guarantee Discrete Blocks: 

When you are using the access methods that provide blocking and unblocking 
of records (QSAM, QISAM, and BISAM), it is necessary that every task 
updating the data set ensure that it is not updating a block that contains 
a record being updated by any other task. There are no facilities in the 
operating system for ensuring that discrete blocks are being processed by 
different tasks. 

ENQ on Block: 

If you are updating a shared data set (specified by coding DISP=SHR on the 
DD statement) using BSAM or BPAM, your task and all other tasks must 
serialize processing of each block of records by issuing an ENQ macro 
instruction before the READ macro and a DEQ macro after the CHECK macro 
that follows the WRITE macro you issued to update the record. If you are 
using BDAM, the same procedure may be used; however, BDAM provides for 
enqueuing on a block of records using the READ exclusive option, which is 
requested by coding MACRF=X in the DCB and an X in the type operand of the 
READ and WRITE macro instructions. See "Exclusive Control for Updating" in 
the section "Processing a Direct Data Set" of Part 2 for an example of the 
use of the BDAM macros. 

Figure 24. JCL, Macro Instructions, and Procedures Required to Share a Data 
Set Using Multiple DCBs 


Figure 25 describes the macros you can use to serialize 
processing of a shared data set when a single DCB is being 
shared by several tasks in a job step. The DISP=SHR 
specification on the DD statement is not required. 
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Data sets can also be shared both ways at the same time : more 
than one DCB can be opened for a shared data set, while more 
than one task can be sharing one of the DCBs. Under this 
condition, the serialization techniques specified for indexed 
sequential and direct data sets in the Figure 24 satisfy the 
requirement. For sequential and partitioned data sets, the 
techniques specified in Figure 24 and Figure 25 must be used. 

More information on opening and closing data sets by more than 
one task is contained in Part 2, "Opening and Closing a Data 
Set." 

SHARED DIRECT-ACCESS STORAGE DEVICES: At some installations, a 
direct-access storage device is shared by two or more 
independent computing systems. Tasks executed on these systems 
can share data sets stored on the device. For details, refer to 
0S/VS2 System Programming Library: Supervisor . 
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A SINGLE SHARED DOB 


Access Mode 

Access Method 

BSAMiBPAM, 
BDAM Create 

QSAM 

BDAM 

QISAM 

BISAM 

Input 

ENQ 

ENQ 

No Action 
Required 

ENQ 

ENQ 

Output 

ENQ 

ENQ 

No Action 
Required 

ENQ and Key 
Sequence 

ENQ 

Update 

ENQ 

ENQ 

ENQ on Block 

ENQ 

ENQ 


ENQ: 

When a data set is being shared by two or more tasks in the same job step 
(all o-f which must be using the same DCB), each task processing the data 
set must issue an ENQ macro instruction on a predefined resource name 
before issuing the macro or macros that begin the input/output operation. 
Each task must also release exclusive control by issuing the DEQ macro 
instruction at the next sequential instruction following the input/output 
macro. If, however, you are processing an indexed sequential data set 
sequentially using the SETL and ESETL macros, you must issue the ENQ macro 
before the SETL macro and the DEQ macro after the ESETL macro. Note also 
that if two tasks are writing different members of a partitioned data set, 
each task should issue the ENQ macro instruction before the FIND macro and 
issue the DEQ macro after the STOW macro that completes processing of the 
member. Additional reference information on the ENQ and DEQ macros is 
presented in QS/VS2 Supervisor Services and Macro Instructions . For an 
example of the use of ENQ and DEQ macro instructions with BISAM, see 
Figure 59. 

No Action Required: 

Sharing a Direct Data Set : BDAM supports multiple task users of a single 
DCB when working with existing data sets. When operating in load mode, 
however, only one task may use the DCB at a time. The following 
restrictions and comments apply when operating in a multitasking mode with 
existing data sets : 

• Subpool 0 must be shared. 

• The user should insure that a WAIT or CHECK macro has been issued for 
all outstanding BDAM requests before the task issuing the READ or 
WRITE macro terminates. In case of abnormal termination this can be 
done through a STAE/5TAI or ESTAE exit. 

• FREEDBUF and/or RELEX macros should be issued to free any resources 
that could still be held by the terminating task. This can be done 
during or after task termination. 

ENQ on Block: 

When updating a shared BDAM data set, every task must use the BDAM 
exclusive control option, which is requested by coding MACRF=X in the DCB 
macro and an X in the type operand of the READ and WRITE macro 
instructions. See "Exclusive Control for Updating" in this book for an 
example of the use of BDAM macros. Note that all tasks sharing a data set 
must share subpool 0 (see the ATTACH macro description in 0S/VS2 
Supervisor Services and Macro Instructions ). 

Key Sequence: 

Tasks sharing a QISAM load-mode DCB must ensure that the records to be 
written are presented in ascending key sequence; otherwise, a sequence 
check will result in (1) control being passed to the SYNAD routine 
identified by the DCB, or (2) if there is no SYNAD routine, termination of 
the task. 

Figure 25. Macro Instructions and Procedures Required to Share a Data Set 
Using a Single DCB 
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PART 2: DATA MANAGEMENT PROCESSING PROCEDURES 


DATA PROCESSING TECHNIQUES 


The operating system allows you to concentrate most of your 
efforts on processing the records read or written by the data 
management routines. To get the records read and written, your 
main responsibilities are to describe the data set to be 
processed, the buffering techniques to be used, and the access 
method. An access method has been defined as the combination of 
data set organization and the technique used to gain access to 
the data. Data access techniques are discussed here in two 
categories—queued and basic.' 


QUEUED ACCESS TECHNIQUE 

The queued access technique provides GET and PUT macro 
instructions for transmitting data within virtual storage. These 
macro instructions cause automatic blocking and deblocking of 
the records stored and retrieved. Anticipatory (look-ahead) 
buffering and synchronization (overlap) of input and output 
operations with central processing unit (CPU) processing are 
automatic features of the queued access technique. 

Because the operating system controls.buffer processing, you can 
use as many input/output (I/O) buffers as needed without 
reissuing GET or PUT macro instructions to fill or empty 
buffers. Usually, more than one input block is in storage at any 
given time, so I/O operations do not delay record processing. 

Because the operating system synchronizes input/output with 
processing, you need not test for completion, errors, or 
exceptional conditions. After a GET or PUT macro instruction is 
issued, control is not returned to your program until an input 
area is filled or an output area is available. Exits to error 
analysis (SYNAD) and end-of-volume or end-of-data (EODAD) 
routines are automatically taken when necessary. 


GET—Retrieve a Record 

The GET macro instruction obtains a record from an input data 
set. It operates in a logical sequential and device-independent 
manner. As required, the GET macro instruction schedules the 
filling of input buffers, deblocks records, and directs input 
error recovery procedures. For sequential data sets, it also 
merges record segments into logical records. After all records 
have been processed and the GET macro instruction detects an 
end-of-data indication, the system automatically checks labels 
on sequential data sets and passes control to your end-of-data 
(EODAD) routine. If an end-of-volume condition is detected for a 
sequential data set, the system provides automatic volume 
switching if the data set extends across several volumes or if 
concatenated data sets are being processed. If you specify 
0PTCD=Q in the DOB, GET causes input data to be translated from 
ASCII to EBCDIC. 


PUT—Write a Record 

The PUT macro instruction places a record into an output data 
set. Like the GET macro instruction, it operates in a logical 
sequential and device-independent manner. As required, the PUT 
macro instruction schedules the emptying of output buffers, 
blocks records, and handles output error correction procedures. 
For sequential data sets, it also initiates automatic volume 
switching and label creation, and also segments records for 
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spanning. If you specify 0PTCD=Q in the DCB# PUT causes output 
to be translated from EBCDIC to ASCII. 

If the PUT macro instruction is directed to a card punch or 
printer# the system automatically adjusts the number of records 
or record segments per block of format-F or format-V blocks to 
1. Thus# you can specify a record length CLRECL) and blocksize 
(BLKSIZE) to provide an. optimum blocksize if the records are 
temporarily placed on magnetic tape or a direct-access volume. 

For spanned variable-length records# the blocksize must be 
equivalent to the length of one card or one print line. Record 
size may be greater than blocksize in this case. 


PUTX—Write an Updated Record 

The PUTX macro instruction is used to update a data set or to 
create an output data set using records from an input data set. 
as a base. PUTX updates# replaces# or inserts records from 
existing data sets but does not create records. 

When you use the PUTX macro instruction to update# each record 
is returned to the data set referred to by a previous locate 
mode GET macro instruction. The buffer containing the updated 
record is flagged and written back to the same location on the 
direct-access storage device from which it was read. The block 
is not written until a GET macro instruction is issued for the 
next buffer, except when a spanned record is to be updated. In 
that case# the block is written with the next GET macro 
instruction. 

When the PUTX macro instruction is used to create an output data 
set# you can add new records by using the PUT macro instruction. 
As required# the PUTX macro instruction blocks records# 
schedules the writing of output buffers# and handles output 
error correction procedures. 


Parallel Input Processing (QSAM Only) 

QSAM parallel input processing may be used to process two or 
more input data sets concurrently# such as sorting or merging 
several data sets at the same time. This eliminates the need for 
issuing a separate GET macro instruction to each DCB processed. 
The get routine for parallel input processing selects a DCB with 
a ready record and then transfers control to the normal get 
routine. If there is no DCB with a ready record# a multiple WAIT 
macro instruction is issued. 

Parallel input processing provides a logical input record from a 
queue of data sets with equal priority. The function supports 
QSAM with input processing# simple buffering# locate or move 
mode# and fixed# variable# or undefined length records. Spanned 
records# track-overflow records# dummy data sets# and SYSIN data 
sets are not supported. 

Parallel input processing can be interrupted at any time to 
retrieve records from a specific data set# or to issue control 
instructions to a specific data set. When the retrieval process 
has been completed# parallel input processing may be resumed. 

Data sets can be added to or deleted from the data set queue at 
any time. It is important to note# however# that as each data 
set reaches an end-of-data condition# the data set must be 
removed from the queue with the CLOSE macro instruction before a 
subsequent GET macro instruction is issued for the queue; 
otherwise# the task may be terminated abnormally. 

A request for parallel input processing is indicated by 
including the address of a parallel data access block CPDAB) in 
the DCB exit list. For additional information on the DCB exit 
list, see "Exit List CEXLST)." 
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With the use of the PDAB macro instruction, you can create and 
format a work area that identifies the maximum number of DCBs 
that can be processed at any one time. If you exceed the maximum 
number of entries indicated in the PDAB macro when adding a DOB 
to the queue with the OPEN macro, the data set will not be 
available for parallel input processing; however, it may be 
available for sequential processing. 

When issuing a parallel GET macro, register 1 must always point 
to a PDAB. You may load the register or let the GET macro do it 
for you. When control is returned to you, register 1 contains 
the address of a logical record from one of the data sets in the 
queue; registers 2-13 contain their original contents at the 
time the GET macro was issued; registers 14, 15, and 0 are 
changed. You can locate the data set from which the record was 
retrieved through the PDAB. A.fullword address in the PDAB 
(PDADCBEP) points to the address of the DCB. It should be noted 
that this pointer may be invalid from the time a CLOSE macro is 
issued to the issuing of the next parallel GET macro. 

In Figure 26, not more than three data sets (MAXDCB=3 in the 
PDAB operand) will be open for parallel processing at any given 
time. Assuming that data definition statements and data sets are 
supplied, DATASET1, DATASET2, and DATASET3 will be opened for 
parallel input processing as specified in the input processing 
OPEN macro instruction. Other attributes of each data set are 
QSAM (MACRF=G), simple buffering by default, locate or move mode 
(MACRF=L or M), fixed length records (RECFM=F), and exit list 
entry for a PDAB CX’92’). Note that both locate and move modes 
may be used in the same data set queue. The mapping macros, DCBD 
and PDABD, are used to reference the DCBs and the PDAB 
respectively. 

Following the OPEN macro instruction, tests are made to 
determine whether the DCBs were opened for parallel processing. 
If not, the sequential processing routine is given control. 

When one or more data sets are opened for parallel processing, 
the get routine retrieves a record, saves the pointer in 
register 10, processes the record, and writes it to DATASET4. 
This process continues until an end-of-data condition is 
detected on one of the input data sets; the end-of-data routine 
locates the completed input data set and removes it from the 
queue with the CLOSE macro instruction. A test is then made to 
determine whether any data sets remain on the queue. Processing 
continues in this manner until the queue is empty. 


BASIC ACCESS TECHNIQUE 

The basic access technique provides the READ and WRITE macro 
instructions for transmitting data between virtual and auxiliary 
storage. This technique is used when the operating system cannot 
predict the sequence in which the records are to be processed or 
when you do not want some or all of the automatic functions 
performed by the queued access technique. Although the system 
does not provide anticipatory buffering or synchronized 
scheduling, macro instructions are provided to help you program 
these operations. 
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BZ 

TM 

BZ 

TM 

BZ 

GETRTN 

GET 

LR 

PUT 

B 

EODRTN 

EQU 

L 

L 

CLOSE 

CLC 

BL 

DATASET1 

DCB 

DATASET2 

DCB 

DATASET3 

DCB 

DATASET4 

DCB 

DCBQUEUE 

PDAB 

SET3XLST 

DC 

ZEROS 

DC 

DCBD 

PDABD 


(DATASET1,(INPUT),DATASET2,(INPUT),DATASET3, X 

(INPUT)/DATASET4,(OUTPUT)) 

DATASET1+DCBQSWS-IHADCB/DCBPOPEN Opened for parallel 

processing 

SEQRTN Branch on no to sequential routine 

DATASET2+DCBQSWS-IHADCB/DCBPOPEN 

SEQRTN 

DATASET3+DCBQSWS-IHADCB,DCBPOPEN 
SEQRTN 

DCBQUEUE/BUFFERAD»TYPE=P 

10/1 Save record pointer 

Record updated in place 


DATASET4,(10) 

GETRTN 

* Close DCB which just reached EODAD 

2/DCBQUEUE+PDADCBEP-IHAPDAB 

2 / 0 ( 0 , 2 ) 

(( 2 )) 

ZER0S(2)/DCBQUEUE+PDAN0DCB-IHAPDAB Any DCBs left? 

GETRTN Branch if yes 


DDNAME=DDNAME1,DSQRG=PS,MACRF=GL,RECFM=FB z X 

LRECL=80/E0DAD=E0DRTN/EXIST=SET3XLST 

DDNAME=DDNAME2/DS0RG=PS,MACRF=GL,RECFM=FB/ X 

LRECL=80/EODAD=EODRTN/EXLST=SET3XLST 

DDNANE=DDNAME3,DS0RG=PS,MACRF=GMC,RECFM=FB, X 

LRECL=80,E0DAD=E0DRTN,EXLST=SET3XLST 

DDNAME=DDNAME4/DS0RG=PS,MACRF=PM/RECFM=FB, X 

LRECL=80 

MAXDCB=3 

OF’O’/X’92’/AL3(DCBQUEUE) 

X’0000' 

DS0RG=QS 


Notei The number of bytes required for PDAB is equal to 24+8n> where n is the 
value of the keyword/ MAXDCB. 

Figure 26. Parallel Processing of Three Data Sets 


The READ and WRITE macro instructions process blocks/ not 
records. Thus/ blocking and deblocking of records is your 
responsibility. Buffers/ allocated by either you or the 
operating system/ are filled or emptied individually each time a 
READ or WRITE macro instruction is issued. Moreover/ the READ 
and WRITE macro instructions only initiate input/output 
operations. To ensure that the operation is completed 
successfully/ you must issue a CHECK macro instruction to test 
the data event control block (DECB). (The only exception to this 
is that when the SYNAD or EODAD routine is entered/ a CHECK 
macro instruction should not be issued to previously outstanding 
READ or WRITE requests.) The number of READ or WRITE macro 
instructions issued before a CHECK macro instruction is used 
should not exceed the specified number of channel programs 
(NCP). 

GROUPING RELATED CONTROL BLOCKS IN A PAGING ENVIRONMENT: In an 

OS/VS system/ related control blocks (the DCB and DECB) and data 
areas (buffers and key areas) should be coded so they assemble 
in the same area of your program. This will reduce the number of 
paging operations required to read from and write to your data 
set. 
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USING OVERLAPPED I/O WITH BSAM • When using BSAM with overlapped 
I/O (multiple I/O requests outstanding at one time), more than 
one DECB must be used. A different DECB should be specified for 
each channel program. For example, if you specify NCP=3 in your 
DCB for the data set and you are reading records from the data 
set, you should code the following macros in your program: 


READ DECB1,... 
READ DECB2, . . . 
READ DECB3, . . . 
CHECK DECB1 
CHECK DECB2 
CHECK DECB3 


USING OVERLAPPED I/O WITH BDAM ' When using BDAM with overlapped 
I/O requests, a different DECB must be used for each request 
that will be outstanding when another request is issued. In 
addition, consecutive requests for the same record (such as a 
write followed by a read) must not be overlapped. In this case, 
the completion of the write request must be tested prior to 
issuance of the read request. 


READ—Read a Block 

The READ macro instruction retrieves a data block from an input 
data set and places it in a designated area of virtual storage. 
To allow overlap of the input operation with processing, the 
system returns control to your program before the read operation 
is completed. The DECB created for the read operation must be 
tested for successful completion before the record is processed 
or the DECB is reused. 

If an indexed sequential data set is being read, the block is 
brought into virtual storage and the address of the record is 
returned to you in the DECB. 

When you use the READ macro instruction for BSAM to read a 
direct data set with spanned records and keys and you specify 
BFTEK=R in your DCB, the data management routines displace 
record segments after the first in a record by key length. Thus, 
you can expect the block descriptor word and the segment 
descriptor word at the same locations in your buffer or buffers, 
regardless of whether you read the first segment of a record, 
which is preceded in the buffer by its key, or a subsequent 
segment, which does not have a key. This procedure is called 
offset reading . 

You can specify variations of the READ macro instruction 
according to the organization of the data set being processed 
and the type of processing to be done by the system as follows: 

Sequential 

SF Read the data set sequentially. 

SB Read the data set backward (magnetic tape, format-F and 

format-U only). When RECFM=FBS, data sets with the last 
block truncated cannot be read backward. 

Indexed Sequential 

K Read the data set. 

KU Read for update. The system maintains the device address of 
the record; thus, when a WRITE macro instruction returns 
the record, no index search is required. 

Direct 

D Use the direct access method. 
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I 

K 

F 

X 

R 

U 


Locate the block using a block identification. 

Locate the block using a key. 

Provide device position feedback. 

Maintain exclusive control of the block. 

Provide next address feedback. 

Next address can be a capacity record or logical record, 
whichever occurred first. 


WRITE—write a Block 

» The WRITE macro instruction places a data block in an output 
data set from a designated area of virtual storage. The WRITE 
macro instruction can also be used to return an updated record 
to a data set. To allow overlap of output operations with 
processing, the system returns control to your program before 
the write operation is completed. The DECB created for the write 
operation must be tested for successful completion before the 
DECB can be reused. For ASCII tape data sets, do not issue more 
than one WRITE on the same record, because the WRITE macro 
instruction causes the data in the record area to be translated 
from EBCDIC to ASCII. 


As with the READ macro instruction, you can specify variations 
of the WRITE macro instruction according to the organization of 
the data set and the type of processing to be done by the system 
as foHows'* 

Sequential 

SF Write the data set sequentially. 

SFR Write the data set sequentially with next-address 

feedback. 


Indexed Sequential 

K Write a block containing an updated record, or replace a 

record with a fixed, unblocked record having the same 
key. The record to be replaced need not have been read 
into virtual storage. 

KN Write a new record or change the length of a 

variable-length record. 

Direct 


SD Write a dummy fixed-length record. 

SZ Write a capacity record (RO). The system supplies the 

data, writes the capacity record, and advances to the 
next track. 

D Use the direct access method. 

I Search argument identifies a block. 

K Search argument is a key. 

A Add a new block. 

F Provide record location data (feedback). 

X Release exclusive control. 
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CHECK—Test Completion of Read or Write Operation 


When processing a data set/ you can test for completion of a 
READ or WRITE request by issuing a CHECK macro instruction. The 
system tests for errors and exceptional conditions in the data 
event control block (DECB). Successive CHECK macro instructions 
issued for the same data set must be issued in the same order as 
the associated READ and WRITE macro instructions. 

The check routine passes control to the appropriate exit 
routines specified in the DCB for error analysis (SYNAD) or, for 
sequential data sets, end-of-data (EODAD). It also automatically 
initiates end-of-volume procedures (volume switching or 
extending output data sets). 

If you specify 0PTCD=Q in the DCB, CHECK causes input data to be 
translated from ASCII to EBCDIC. 


WAIT—Wait for Completion of a Read or Write Operation 

When processing a data set, you can test for completion of any 
READ or WRITE request by issuing a WAIT macro instruction. The 
input/output operation is synchronized with processing, but the 
DECB is not checked for errors or exceptional conditions, nor 
are end-of-volume procedures initiated. Your program must 
perform these operations. 

For BDAM and BISAM, a WAIT macro must be issued for each READ or 
WRITE macro if MACRF=C is not coded in the associated DCB. When 
MACRF=C is coded, and at all times for BSAM and BPAM, a CHECK 
macro must be issued for each READ or WRITE macro. Since the 
CHECK macro incorporates the function of the WAIT macro, a WAIT 
is normally redundant for those access methods. The ECBLIST form 
of the WAIT macro may be useful, though, in selecting which of a 
number of outstanding events should be checked first. 

The WAIT macro instruction can be used to await completion of 
multiple read and write operations. Each operation must then be 
checked or tested separately. Example? You have opened an input 
DCB for BSAM with NCP=2, and an output DCB for BISAM with NCP = 1 
and without specifying MACRF=C. You have issued two BSAM READ 
macros and one BISAM WRITE macro. You now issue the WAIT macro 
with ECBLIST pointing to the BISAM DECB and the first BSAM DECB. 
(Since BSAM requests are serialized, the first request must 
execute before the second one.) When you regain control, you 
will inspect the DECBs to see which has completed (second bit 
on). If it was BISAM, you will issue another WRITE macro. If it 
was BSAM, you will issue a CHECK macro and then another READ 
macro. 


Data Event Control Block (DECB) 

A data event control block is a 16- to 32-byte area reserved by 
each READ or WRITE macro instruction. It contains control 
information and pointers to standard status indicators. It is 
described in detail in Appendix A of 05/VS2 MVS Data Management 
Macro Instructions . 

The DECB is examined by the check routine when the I/O operation 
is completed to determine if an uncorrectable error or 
exceptional condition exists. If it does, control is passed to 
your SYNAD routine. If you have no SYNAD routine, the task is 
abnormally terminated. 
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ERROR HANDLING 


The basic and queued access techniques both provide special 
macro instructions for analyzing input/output errors. These 
macro instructions can be used in 5YNAD routines and in error 
analysis routines that are entered directly when you use the 
basic access technique with indexed sequential data sets. 


SYNADAF—Perform SYNAD Analysis Function 

The SYNADAF macro instruction analyzes the status, sense, and 
exceptional condition code data that is available to your error 
analysis routine. It produces an error message that your routine 
can write into any appropriate data set. The message is in the 
form of an unblocked variable-length record, but you can write 
it as a fixed-length record by omitting the block length and 
record length fields that precede the message text. 

The text of the message is 120 characters long, and begins with 
a field of 36 or 42 blanks; you can use the blank field to add 
your own remarks to the message. Following is a typical message 
with the blank field omitted : 

,TESTJOBb,STEP2bbb,283,TA,MASTERbb,READb,DATA CHECKbbbbb, 
0000015,BSAM 

Note: in the above example, a b indicates a blank. 

This message indicates that a data check occurred during reading 
of the fifteenth block of a data set. The data set was 
identified by a DD statement named MASTER, and was on a 
magnetic-tape volume on unit 283. The name of the job was 
TESTJOB; the name of the job step was STEP2. 

If the error analysis routine is entered because of an input 
error, the first 6 bytes of the message (bytes 8-13) contain 
binary information. If no data was transmitted or if the access 
method is QISAM, the first 6 bytes are blanks or binary zeros. 

If the error did not prevent data transmission, the first 6 
bytes contain the address of the input buffer and the number of 
bytes read. You can use this information to process records from 
the block; for example, you might print each record after 
printing the error message. Before printing the message, 
however, you should replace this binary information with EBCDIC 
characters. 

The SYNADAF macro instruction provides its own save area and 
makes this area available to your error analysis routine. When 
used at the entry point of a SYNAD routine, it fulfills the 
routine’s responsibility for providing a save area. 


SYNADRLS—Release SYNADAF Message and Save Areas 

The SYNADRLS macro instruction releases the message and save 
areas provided by the SYNADAF macro instruction. You must issue 
this macro instruction before returning from the error analysis 
routine. 


ATLAS—Perform Alternate Track Location Assignment 

The ATLAS macro instruction enables your program to recover from 
permanent input/output errors when processing a data set in 
direct-access storage. After a data check, or in certain 
missing-address-marker conditions, you can issue ATLAS to assign 
an alternate track to replace the error track or transfer data 
from the error track to the alternate track. 

The use of this macro requires a knowledge of channel 
programming. A detailed description of the macro instruction and 
its use is included in QS/VS2 System Programming Library: Data 
Management . 
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If you do not use the ATLAS macro instruction, you can use the 
IEHATLAS utility program to perform the same function. The 
principal difference between the macro instruction and the 
utility program is that the latter provides error recovery only 
after your own program has been completed. For a detailed 
description of IEHATLAS, refer to OS/VS Utilities . 


SELECTING AN ACCESS METHOD 

Access methods are identified primarily by the data set 
organization to which they apply. For instance, BDAM is the 
basic access method for direct organization. Nevertheless, there 
are times when an access method identified with one organization 
can be used to process data set usually thought of as organized 
in a different manner. Thus, a data set created by the basic 
access method for sequential organization (BSAM) may be 
processed by the basic direct access method (BDAM). If the 
queued access technique is used to process a sequential data 
set, the access method is referred to as the queued sequential 
access method (QSAM). 

Basic access methods are used for all data organizations, while 
queued access methods apply only to sequential and indexed 
sequential data sets as shown in Figure 27. 


Data Set 

Organization 

Access 

Technique 


Basic 

Queued 

Sequential 

BSAM 

QSAM 

Partitioned 

BPAM 


Indexed Sequential 

BISAM 

QISAM 

Direct 

BDAM 



Figure 27. Data Management Access Methods 


It is possible to control an I/O device directly while 
processing a data set with any data organization without using a 
specific access method. The execute channel program (EXCP) macro 
instruction uses the system programs that provide for scheduling 
and queuing I/O requests, efficient use of channels and devices, 
data protection, interruption procedures, error recognition and 
retry. Complete details about the EXCP macro are in 0S/VS2 
System Programming Library- Data Management . 

Temporary data sets can be handled by a facility called virtual 
I/O (VIO). Data sets for which VIO is specified are located in 
external page storage. However, to the access methods (BDAM, 
BPAM, BSAM, QSAM, and EXCP), the data sets appear to reside on a 
real direct-access storage device. VIO provides these 
advantages'- 

♦ Elimination of some of the usual I/O device allocation and 
data management overhead for temporary data sets. 

• Generally more efficient use of direct-access storage space. 

To use VIO, you must specify VI0=YES in the UNITNAME macro 
during system generation, and you must specify a unit name 
(defined in the UNITNAME macro) on the DD statement for your 
data set. For additional information on VIO, see 05/VS2 System 

Programming Libr a ry’ _ Initia 1ization and Tuning Guide . For 

information on the UNITNAME macro, see QS/VS2 System Programming 
Library-' System Generation Re feren ce. For information on changes 
to the DD statement, see QS/VS2 JCL . 
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OPENING AND CLOSING A DATA SET 


Although your program has been assembled, the various data 
management routines required for I/O operations are not a part 
of the object code. In other words, your program is not 
completely assembled until the DCBs are initialised for 
execution. You accomplish initialization by issuing the OPEN 
macro instruction. After all DCBs have been completed, the 
system ensures that all required access method routines are 
loaded and ready for use and that all channel command word lists 
and buffer areas are ready. 

Access method routines are selected and loaded according to data 
control fields that indicate: 

• Data organization 

• Buffering technique 

• Access technique 

• I/O unit characteristics 

This information is used by the system to allocate 
virtual-storage space and load the appropriate routines. These 
routines, the channel command word CCCW) lists, and buffer areas 
created automatically by the system remain in virtual storage 
until the close routine signals that they are no longer needed 
by the DCB that was using them. 

When I/O operations for a data set are completed, you should 
issue a CLOSE macro instruction to return the DCB to its 
original status, handle volume disposition, create data set 
labels, complete writing of queued output buffers, and free 
virtual and auxiliary storage. 

MANAGING BUFFER POOLS WHEN CLOSING DATA SETS: After closing the 
data set, you should issue a FREEPOOL macro instruction to 
release the virtual storage used for the buffer pool. If you 
plan to process other data sets, use FREEPOOL to regain the 
buffer pool storage space. If you expect to reopen a data set 
using the same DCB, use FREEPOOL unless the buffer pool created 
the first time the data set was opened will meet your needs when 
you reopen the data set. FREEPOOL is discussed in more detail in 
the section "Buffer Pool Construction." 

After the data set has been closed, the DCB can be used for 
another data set. If you do not close the data set before a task 
terminates, the operating system closes it automatically. If the 
DCB is not available to the system at that time, the operating 
system abnormally terminates the task, and data results can be 
unpredictable. Note, however, that the operating system cannot 
automatically close any open data sets after the normal 
termination of a program that was brought into virtual storage 
by the loader. Therefore, loaded programs must include CLOSE 
macro instructions for all open data sets. 

SIMULTANEOUS OPENING AND CLOSING OF MULTIPLE DATA SETS: An OPEN 
or CLOSE macro instruction can be used to initiate or terminate 
processing of more than one data set. Simultaneous opening or 
closing is faster than issuing separate macro instructions; 
however, additional storage space is required for each data set 
specified. The coding examples in Figures 28 and 29 show the 
macro expansions for simultaneous open and close operations. 

OPENING AND CLOSING DATA SETS SHARED BY MORE THAN ONE TASK: When 

more than one task is sharing a data set, the following 
restrictions must be recognized. Failure to adhere to these 
restrictions endangers the integrity of the shared data set. 

• All tasks sharing a DCB must be in the job step that opened 
the DCB (see "Sharing a Data Set"). 




* 
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• Each task sharing a DCB must ensure that all of the input 
and output operations it initiated using a given DCB are 
complete, before the task terminates. A CLOSE macro 
instruction issued for the DCB will ensure termination of 
all input and output operations. 

• A DCB can be closed only by the task that opened it. 

Considerations for Opening and Closing Data Sets: 

• Two or more DCBs should never be concurrently open for 
output to the same data set on a direct-access device, 
except with the basic indexed sequential access method 
(BISAM). Otherwise the end-of-file record written by CLOSE 
for one DCB may overlay data associated with another DCB. 

• If one DCB is concurrently open for input and one for output 
to the same data set on a direct-access device, the input 
DCB may be unable to read what the output DCB wrote if the 
output DCB extended the data set. 

• If you want to use the same DD statement for two or more 
DCBs, you cannot specify parameters for fields in the first 
DCB and then be assured of obtaining the default parameters 
for the same fields in any subsequent DCB using the same DD 
statement. This is true for both input and output and is 
especially important when you are using more than one access 
method. Any action on one DCB that alters the JFCB affects 
the other DCB(s) and thus can cause unpredictable results. 
Therefore, unless the parameters of all DCBs using one DD 
statement are the same, you should use separate DD 
statements. 

• Associated data sets for the 3525 Card Punch can be opened 
in any order, but all data sets must be opened before any 
processing can begin. Associated data sets can be closed in 
any order, but once a data set has been closed, I/O 
operations cannot be performed on any of the associated data 
sets. See OS and OS/VS Programming Support for the IBM 3505 
Card Reader and IBM 3525 Card Punch for more information. 

• Volume disposition specified in the OPEN or CLOSE macro 
instruction can be overridden by the system if necessary. 
However, you need not be concerned; the system automatically 
requests the mounting and demounting of volumes, depending 
upon the availability of devices at a particular time. 
Additional information on volume disposition is provided in 
0S/VS2 JCL . 

There are two classes of errors that can occur during open, 
close, and end-of-volume processing; determinate and 
indeterminate errors. Determinate errors are errors associated 
with a system completion code. For example, a condition 
associated with the 213 completion code with a return code of 04 
might be detected during open processing, indicating that a 
format-1 DSCB could not be found for a data set being opened. 
Indeterminate errors are errors that cannot be anticipated, such 
as a program check. 

If a determinate error occurs during the processing resulting 
from a concurrent OPEN or CLOSE macro instruction, an attempt 
will be made to complete open or close processing of the DCBs 
that are not associated with the DCB in error. Note that you can 
also choose to abnormally terminate the task immediately by 
coding a DCB ABEND exit routine that indicates the "immediate 
termination" option (see "DCB ABEND Exit"). When all open or 
close processing is completed, abnormal termination processing 
is begun. Abnormal termination involves forcing all DCBs 
associated with a given OPEN or CLOSE macro to close status, 
thereby freeing all storage, devices, and other system resources 
related to the DCBs. 
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If an indeterminate error (such as a program check) occurs 
during open, close, or EOV processing, no attempt is made by the 
system control program to complete concurrent open or close 
processing. The DCBs associated with the OPEN or CLOSE macro are 
forced to close status if possible, and the resources related to 
each DOB are freed. 

To determine the status of any DCB after an indeterminate error, 
the OPEN (CLOSE) return code in register 15 must be interrogated 
for the following values’- 

0 All entries in the parameter list opened successfully. 

4 All entries in the parameter list have successfully 

completed open, but one or more entries have a warning 
message. 

8 One or more entries in the parameter list were not opened 

successfully. The entries with errors were restored to their 
pre-open status. 

12 One or more entries in the parameter list were not opened 

successfully. The entries with errors were not restored, and 
cannot be reopened without restoration. 

For more information on error processing and system recovery, 
see QS/VS2 System Programming Librarv ; Supervisor . 

* During task termination the system issues a CLOSE macro for 
each data set which is still open. If this is an abnormal 
termination, the QSAM close routines (which would normally 
finish processing buffers) are bypassed. Any outstanding I/O 
requests are purged. Thus, your last data records may be 
lost for a QSAM output data set. 

• It is a good procedure to close an ISAM data set before task 
termination because, if an I/O error is detected, the ISAM 
close routines cannot return the problem program registers 
to the SYNAD routine, causing unpredictable results. 


OPEN—Prepare a Data Set for Processing 

The OPEN macro instruction is used to complete a data control 
block for an associated data set. The method of processing and 
the volume positioning instruction in the event of an 
end-of-volume condition can be specified. 

PROCESSING METHOD: You can process a data set as either input or 
output. This is done by coding INPUT, OUTPUT, or EXTEND as the 
processing method operand of the OPEN macro. For BSAM, code 
INOUT, OUTIN, or OUTINX. If the data set resides on a 
direct-access volume, you can code UPDAT in the processing 
method operand to indicate that records can be updated. By 
coding RDBACK in this operand, you can specify that a 
magnetic-tape volume containing format-F or format-U records is 
to be read backward. Variable-length records cannot be read 
backward. If the processing method operand is omitted from the 
OPEN macro instruction, INPUT is assumed. The operand is ignored 
by the basic indexed sequential access method (BI5AM); it must 
be specified as OUTPUT or EXTEND when you are using the queued 
indexed sequential access method (QI5AM) to create an indexed 
sequential data set. You can override the INOUT, OUTIN, UPDAT, 
or OUTINX at execution by using the LABEL parameter of the DD 
statement, as discussed in Q5/VS2 JCL . 

SYSIN and SYSOUT data sets must be opened for INPUT and OUTPUT, 
respectively. INOUT is treated as INPUT, OUTIN, EXTEND, or 
OUTINX is treated as OUTPUT. UPDAT and RDBACK cannot be used. 

In Figure 28, the data sets associated with three DCBs are to be 
opened simultaneously. 
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Figure 28. 

Opening Three Data 

Sets Simultaneously 


Since no processing method operand is specified for TEXTDCB, the 
system assumes INPUT. Both CONVDCB and PRINTDCB are opened for 
output. No volume positioning options are specified; thus, the 
disposition indicated by the DD statement DISP parameter is 
used. 

At execution, the SVC 19 instruction passes control to the Open 
routine, which then initializes the three DCBs and loads the 
appropriate access method routines. 


CLOSE—Terminate Processing of a Data Set 

The CLOSE macro instruction is used to terminate processing of a 
data set and release it from a DCB. The volume positioning that 
is to result from closing the data set can also be specified. 
Volume positioning options are the same as those that can be 
specified for end-of-volume conditions in the OPEN macro 
instruction or the DD statement. An additional volume 
positioning option, REWIND, is available and can be specified by 
the CLOSE macro instruction for magnetic-tape volumes. REWIND 
positions the tape at the load point regardless of the direction 
of processing. 

You can code CLOSE TYPE=T and perform some close functions for 
sequential data sets on magnetic tape and direct-access volumes 
processed with BSAM. When you use TYPE=T, the DCB used to 
process the data set maintains its open status, and you should 
not issue another OPEN macro instruction to continue processing 
the same data set. This option cannot be used in a SYNAD 
routine. 

The TYPE=T operand causes the system control program to process 
labels, modify some of the fields in the system control blocks 
for that data set, and reposition the volume (or current volume 
in the case of multi volume data sets) in much the same way that 
the normal CLOSE macro does. When you code TYPE=T, you can 
specify that the volume either be positioned at the end of data 
(the LEAVE option) or be repositioned at the beginning of data 
(the REREAD option). Magnetic-tape volumes are repositioned 
either immediately before the first data record or immediately 
after the last data record; the presence of tape labels has no 
effect on repositioning. Figure 29, which assumes a sample data 
set containing 1000 records, illustrates the relationship 
between each positioning option and the point at which you 
resume processing the data set after issuing the temporary 
close. 

If you code the release (RLSE) operand on the DD statement for 
an output data set, it is ignored by temporary close (CLOSE 
TYPE=T). If the last operation occurring prior to closing the 
data set was a write, any unused space will be released when you 
finally issue the normal CLOSE macro instruction. 
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Figure 29. Record Processed When LEAVE or REREAD is Specified 
for CLOSE TYPE=T 


It is possible to use BSAM to process a data set that is not 
physical-sequential; if you use CLOSE TYPE=T for them, the 
following restrictions apply: 

• The DCB for the data set you are processing on a 
direct-access device must specify either DS0RG=PS or 
DS0RG=PSU for input processing, and either D50RG r PS> 
DS0RG = PSU, DS0RG = P0, or DS0RG = P0U for output processing. 

• The DCB must not be open for input to a member of a 
partitioned data set. 

• If you open a data set on a direct-access device for output 
and issue CLOSE TYPE=T, the volume will be repositioned only 
if the data set was created with DS0RG=PS, DS0RG=PSU, 
DS0RG=P0, or DS0RG=P0U (you cannot specify the REREAD option 
if DS0RG = P0 or DSORG^POU is specified)., (This restriction 
prohibits the use of temporary close following or during the 
building of a BDAM data set that is created by specifying 
BSAM MACRF=WL). 

• If you open the data set for input and issue CLOSE TYPE=T 
with the LEAVE option, the volume will be repositioned only 
if the data set specifies DS0RG=PS or DS0RG=P0. 

Note: When a data control block is shared among multiple tasks, 
only the task that opened the data set can close it unless 
TYPE=T is specified. 

Before issuing the CLOSE macro, a CHECK macro must be issued for 
all DECBs that have outstanding I/O from WRITE macro 
instructions. When CLOSE TYPE=T is specified, a CHECK macro must 
be issued for all DECBs that have outstanding I/O from either 
WRITE or READ macro instructions. 
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In Figure 30, the data sets associated with three DCBs are to be 
closed simultaneously. 
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Because no volume positioning operands are specified, the 
position indicated by the DD statement DISP parameter is used. 

At execution, the SVC 20 instruction passes control to the Close 
routine, which terminates processing of the three data sets and 
returns the three DCBs to their original status. 

RELEASING DATA SETS AND VOLUMES •' You are offered the option of 
being able to release data sets and the volumes the data sets 
reside on when your task is no longer using them. Assuming that 
you are not sharing data sets, these data sets and the volumes 
on which they reside, would otherwise remain unavailable for use 
by other tasks until the job step that opened them is 
terminated. 

There are two ways t.o code the CLOSE macro instruction that can 
result in releasing a data set and the volume on which it 
resides at the time the data set is closed: 

In conjunction with the FREE=CLOSE parameter of the DD statement 
you can code : 

CLOSE (DCB1,DISP) or 
CLOSE (DCB1,REWIND) 

If you do not code FREE=CLOSE on the DD statement, you can code: 
CLOSE C DCB1,FREE) 

See 05/VS2 JCL for information about how to use and code the 
FREE=CLOSE parameter of the DD statement. 

In either case, tape data sets and the volume on which the tape 
is mounted will be freed for use by another job step. Data sets 
on direct-access devices will be freed and the volumes on which 
they reside will be freed if no other data sets on the volume 
are open. Additional information on volume disposition is 
provided in 0S/V52 JCL . 

Data sets being temporarily closed (using CLOSE TYPE=T) cannot 
be released at the time the data set is closed. They will be 
released at termination of the job step. 

Refer to OS/VS Data Management Macro Instructions for additional 
information and coding restrictions. 


End-of-Volume Processing 

Control is passed automatically to the data management 
end-of-volume routine when any of the following conditions is 
detected: 
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• Tapemark (input tape volume) 

• Filemark or end of last extent (input direct-access volume) 

• End-of-data indicator (input device other than magnetic tape 
or direct-access volume). An example of this would be the 
last card read on a card reader. 

• End of reel (output tape volume) 

• End of extent (output direct-access volume) 

You may issue a force end-of-volume (FEOV) macro instruction 
before the end-of-volume condition is detected. 

If the LABEL parameter of the associated DD statement indicates 
standard labels, the end-of-volume routine checks or creates 
standard trailer labels. If SUL or AUL is specified, control is 
passed to the appropriate user label routine if it is specified 
in your exit list. 

If multiple-volume data sets are specified in your DD statement, 
automatic volume switching is accomplished by the end-of-volume 
routine. When an end-of-volume condition exists on an output 
data set, additional space is allocated as indicated in your DD 
statement. If no more volumes are specified or if more than 
specified are required, the storage is obtained from any 
available volume on a device of the same type. If no such volume 
is available, your job is terminated. 

VOLUME POSITIONING^ When an end-of-volume condition is detected, 
the system positions the volume according to the disposition 
specified in the DD statement unless the volume disposition is 
specified in the OPEN macro instruction. Volume positioning 
instructions for a sequential data set on magnetic tape can be 
specified as LEAVE or REREAD. 

LEAVE 

positions a labeled tape to the point following the tape 
mark that follows the data set trailer label group, and an 
unlabeled volume to the point following the tape mark that 
follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data 
set header label group, and an unlabeled tape to the point 
preceding the first block of the data set. 

If the tape was last read backward: 

LEAVE 

positions a labeled tape to the point preceding the data 
set header label group, and an unlabeled tape to the point 
preceding the first block of the data set. 

REREAD 

positions a labeled tape to the point following the tape 
mark that follows the data set trailer label group, and an 
unlabeled tape to the point following the tape mark that 
follows the last block of the data set. 

If, however, you want to position the current volume according 
to the option specified in the DISP parameter of the DD 
statement, you code DISP in the OPEN macro instruction. 

DISP 

specifies that a tape volume is to be disposed of in the 
manner implied by the DD statement associated with the data 
set. Direct-access volume positioning and disposition are 
not affected by this parameter of the OPEN macro 
instruction. There are several dispositions that can be 
specified in the DISP parameter of the DD statement; DISP 
can be PASS, DELETE, KEEP, CATLG, or UNCATLG. 


64 0S/VS2 Data Management Services Guide 








The resultant action at the time an end-of-volume condition 
arises depends on (1) how many tape units are allocated to 
the data set and (2) how many volumes are specified for the 
data set in the DD statement. This is determined by the 
UNIT and VOLUME parameters of the DD statement associated 
with the data set. If the number of volumes is greater than 
the number of units allocated, the current volume will be 
rewound and unloaded. If the number of volumes is less than 
or equal to the number of units, the current volume is 
merely rewound. 

A volume positioning instruction can be specified only if 
the processing method operand has been specified. It is 
ignored if devices other than magnetic-tape and 
direct-access are used, or if the number of volumes exceeds 
the number of available units. 

For magnetic-tape volumes that are not being unloaded, 
positioning varies according to the direction of the last 
input operation and the existence of tape labels. 

If the tape was last read forward 1 

LEAVE 

positions a labeled tape to the point following the 
tapemark that follows the data set trailer label group, and 
an unlabeled volume to the point following the tapemark 
that follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data 
set header label group, and an unlabeled tape to the point 
preceding the first block of the data set. 

If the tape was last read backward* 

LEAVE 

positions a labeled tape to the point preceding the data 
set header label group, and an unlabeled tape to the point 
preceding the first block of the data set. 

REREAD 

positions a labeled tape to the point following the 
tapemark that follows the data set trailer label group, and 
an unlabeled tape to the point following the tapemark that 
follows the last block of the data set. 


FEOV—Force End of Volume 

The FEOV macro instruction directs the operating system to 
initiate end-of-volume processing before the physical end of the 
current volume is reached. If another volume has been specified 
for the data set, volume switching takes place automatically. 

The volume positioning options REWIND and LEAVE are available. 

If an FEOV macro is issued for a spanned multi volume data set 
which is being read using QSAM, errors may occur when the next 
GET macro is issued. These errors are documented in the section, 
"Spanned Variable-Length Records" in "Part 1* Introduction to 
Data Management." 

The FEOV macro instruction can only be used when you are using 
BSAM or QSAM. FEOV is ignored if issued for a SYSIN or SYSOUT 
data set. 
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BUFFER ACQUISITION AND CONTROL 


The operating system provides several methods of buffer 
acquisition and control. Each b uffer (vi rtual-s.torage area used 
for intermediate storage of input/output data) usually 
corresponds in length to the sire of a block in the data set 
being processed. When you use the queued access technique, any 
reference to a buffer actually refers to the next record ( buffer 
segment ). 

You can assign more than one buffer to a data set by associating 
the buffer with a buffer pool . A buffer pool must be constructed 
in a virtual-storage area allocated for a given number of 
buffers of a given length. 

The number of buffers you assign to a data set should be a 
tradeoff against the frequency with which you refer to each 
buffer. A buffer that is not referred to for a relatively long 
period of time may be paged out. If this were allowed to happen 
to any considerable degree, it could result in a greater number 
of buffers actually decreasing throughput. 

Buffer segments and buffers within the buffer pool are 
controlled automatically by the system when the queued access 
technique is used. However, you can terminate processing of a 
buffer by issuing a release (RELSE) macro instruction for input 
or a truncate (TRUNC) macro instruction for output. Two 
buffering techniques, simple and exchange, can be used to 
process a sequential data set. Only simple buffering can be used 
to process an indexed sequential data set. 

If you use the basic access technique, you can use buffers as 
work areas rather than as intermediate storage areas. You can 
control them directly, by using the GETBUF and FREEBUF macro 
instructions, or dynamically for BDAM and BISAM, by requesting 
dynamic buffering in your DCB macro instruction and your READ or 
WRITE macro instruction. If you request dynamic buffering, the 
system will automatically provide a buffer each time a READ 
macro instruction is issued. That buffer will be freed when you 
issue a WRITE or FREEDBUF macro instruction. 


BUFFER POOL CONSTRUCTION 

Buffer pool construction can be accomplished in any of three 
ways: 








Statically using the 
Explicitly using the 
Automatically by the 


BUILD macro instruction 

GETPOOL macro instruction 

system when the data set is opened 


If QSAM simple buffering is used, the buffers are automatically 
returned to the pool when the data set is closed. If the buffer 
pool is constructed explicitly or automatically, the virtual 
storage area must be returned to the system by the FREEPOOL 
macro instruction. 


In many applications, fullword or doubleword alignment of a 
block within a buffer is important. You can specify in the DCB 
that buffers are to start on either a doubleword boundary or a 
fullword boundary that is not also a doubleword boundary (by 
coding BFALN^D or F). If doubleword alignment is specified for 
format-V records, the fifth byte of the first record in the 
block is so aligned. For that reason, fullword alignment must be 
requested to align the first byte of the variable-length record 
on a doubleword boundary. The alignment of the records following 
the first in the block depends on the length of the previous 
records. 
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If the BUILD macro instruction is used to construct the buffer 
pool, alignment depends on the alignment of the first byte of 
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BUILD—Construct a Buffer Pool 


When you know, before program assembly, both the number and the 
size of the buffers required for a given data set, you can 
reserve an area of appropriate size to be used as a buffer pool 
Any type of area can be used—for example, a predefined storage 
area or an area of coding no longer needed. 


A BUILD macro instruction, issued during execution of your 
program, structures the reserved storage area into a buffer 
pool. The address of the buffer pool must be the same as that 
specified for the buffer pool control block (BUFCB) in your DCB. 
The buffer pool control block is an 8-byte field preceding the 
buffers in the buffer pool. The number (BUFNO) and length (BUFL) 
of the buffers must also be specified. For QSAM, the length of 
BUFL must be at least the blocksize. 


When the data set using the buffer pool is 
the area as required. You can also reissue 
instruction to reconstruct the area into a 
used by another data set. 


closed, you can reuse 

the BUILD macro 

new buffer pool to be 


You can assign the buffer pool to two or more data sets that 
require buffers of the same length. To do this, you must 
construct an area large enough to accommodate the total number 
of buffers required at any one time during execution. That is, 
if each of two data sets requires five buffers (BUFN0=5), the 
BUILD macro instruction should specify ten buffers. The area 
must also be large enough to contain the 8-byte buffer pool 
control block. 


BUILDRCD—Build a Buffer Pool and a Record Area 

The BUILDRCD macro instruction, like the BUILD macro 
instruction, causes a buffer pool to be constructed in an area 
of virtual storage you provide. In addition, BUILDRCD makes it 
possible for you to access variable-length, spanned records as 
complete logical records, rather than as segments. 

You must be processing with QSAM in the locate mode and you must 
be processing either VS or VBS records, if you want to access 
the variable-length, spanned records as logical records. If you 
issue the BUILDRCD macro before the data set is opened, or 
during your DCB exit routine, you automatically get logical 
records rather than segments of spanned records. 

Only one logical record storage area is built, no matter how 
many buffers are specified; therefore, you can’t share the 
buffer pool with other data sets that may be open at the same 
t i me. 
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GETPOOL—Get a Buffer Pool 

If a specified area is not reserved for use as a buffer pool# or 
you want to defer specifying the number and length of the 
buffers until execution of your program, you should use the 
GETPOOL macro instruction. It enables you to vary the size and 
number of buffers according to the needs of the data set being 
processed. 

The GETPOOL macro instruction structures a virtual-storage area 
allocated by the system into a buffer pool# assigns a buffer 
pool control block# and associates the pool with a specific data 
set. The GETPOOL macro instruction should be issued either 
before opening of the data set or during your DCB exit routine. 

When using GETPOOL with QSAM# specify a buffer length (BUFL) of 
at least as large as the blocksize. 


Automatic Buffer Pool Construction 

If you have requested a buffer pool and have not used an 
appropriate macro instruction by the end of your DCB exit 
routine, the system automatically allocates virtual-storage 
space for a buffer pool. The buffer pool control block is also 
assigned and the pool is associated with a specific DCB. For 
BSAM# a buffer pool is requested by specifying BUFNO. For QSAM# 
BUFNO can be specified or allowed to default to 5. If you are 
using the basic access technique to process an indexed 
sequential or direct data set# you must indicate dynamic buffer 
control. Otherwise, the system does not construct the buffer 
pool automatically. 

Because a buffer pool obtained automatically is not freed 
automatically when you issue a CLOSE macro instruction# you 
should also issue a FREEPOOL or FREEMAIN macro instruction# 
which is discussed in the next section. 


FREEPOOL—Free a Buffer Pool 

Any buffer pool assigned to a DCB either automatically by the 
OPEN macro instruction (except when dynamic buffer control is 
used) or explicitly by the GETPOOL macro instruction should be 
released before your program is terminated. The FREEPOOL macro 
instruction should be issued to release the virtual-storage area 
as soon as the buffers are no longer needed. When you are using 
the queued access technique# a data set must be closed first. 
When you are using exchange buffering, the buffer pool must not 
be released until all the data sets have been closed. 

If the OPEN macro was issued while running under a protect key 
of zero, a buffer pool which was obtained by OPEN should be 
released by issuing the FREEMAIN macro instead of the FREEPOOL 
macro. This is necessary because the buffer pool acquired under 
these conditions will be in storage assigned to subpool 252. 

CONSTRUCTING A BUFFER POOL: Figures 31 and 32 illustrate several 
possible methods of constructing a buffer pool. They do not take 
into account the method of processing or controlling the buffers 
in the pool. 
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Figure 31. Constructing a Buffer Pool From a Static Storage Area 


In Figure 31, a static storage area named INPOOL is allocated 
during program assembly. The BUILD macro instruction, issued 
during execution, arranges the buffer pool into ten buffers; 
each 52 bytes long. Five buffers are assigned to INDCB and five 
to OUTDCB, as specified in the DCB macro instruction for each. 
The two data sets share the buffer pool because both specify 
INPOOL as the buffer pool control block. Notice that an 
additional 8 bytes have been allocated for the buffer pool to 
contain the buffer pool control block. The 4-byte chain pointer 
which occupies the first four bytes of the buffer is included in 
the buffer, so no allowance need be made for this field. 

In Figure 32, two buffer pools are constructed explicitly by the 
GETPOOL macro instructions. Ten input buffers are provided, each 
52 bytes long, to contain one fixed-length record; five output 
buffers are provided, each 112 bytes long, to contain two 
blocked records plus an 8-byte count field (required by ISAM). 
Notice that both data sets are closed before the buffer pools 
are released by the FREEPOOL macro instructions. The same 
procedure should be used if the buffer pools were constructed 
automatically by the OPEN macro instruction. 



GETPOOL 

GETPOOL 

OPEN 

INDCB,10,52 Construct a 10-buffer pool 

OUTDCB,5,112 Construct a 5-buffer pool 

(INDCB,,OUTDCB,(OUTPUT)) 

ENDJOB 

CL05E 

FREEPOOL 

FREEPOOL 

(INDCB,,OUTDCB) 

INDCB Release buffer pools after 

I/O is complete 

OUTDCB 

INDCB 

OUTDCB 

RETURN 

DCB 

DCB 

Return to system control 

DS0RG=PS,BFALN=F,LRECL=52,RECFM=F,E0DAD=ENDJOB,- 

DSORG=IS,BFALN=D,LRECL=52,KEYLEN=10,BLKSIZE=104, 


RKP = 0,RECFM=FB,- 


Figure 32. Constructing a Buffer Pool Using GETPOOL and FREEPOOL 


BUFFER CONTROL 


Your program can use four techniques to control the buffers used 
by your program. The advantages of each depend to a great extent 
upon the type of job you are doing. Simple and exchange 
buffering are provided for the queued access technique. The 
basic access technique provides for either direct or dynamic 
buffer control. 

Although only simple buffering can be used to process an indexed 
sequential data set, buffer segments and buffers within a buffer 
pool are controlled automatically by the operating system. 
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In addition# the queued access technique provides four 
processing modes that determine the extent of data movement in 
virtual storage. Move# data# locate# or substitute mode 
processing can be specified for either the GET or PUT macro 
instruction. The buffer processing mode is specified in the 
MACRF field of the DCB macro instruction. The movement of a 
record is determined as follows** 

• Move mode ? The record is moved from an input buffer to your 
work area, or from your work area to an output buffer. 

• D ata mode (Q5AM format-V spanned records only) : The same as 
the move mode except only the data portion of the record is 
moved, 

• Locate mod e : The record is not moved. Instead# the address 
of the next input or output buffer is placed in register 1. 
For QSAM format-V spanned records, if you have specified 
logical records by specifying BFTEK=A or by issuing the 
BUILDRCD macro instruction# the address returned in register 
1 points to a record area where the spanned record is 
assembled or segmented. 

The PUT-locate routine uses the value in the DCBLRECL field 
to determine whether another record will fit into your 
buffer. Therefore# when you write a short record# you can 
maximize the number of records per block by modifying the 
DCBLRECL field b efore you issue a PUT-locate to get a buffer 
segment for the short record. The processing sequence 
follows* 

1. Register 1 is returned to you with the address of the 
next buffer segment. 

2. Move the record into the output buffer segment. 

3. Put the length of the next (short) record info DCBLRECL. 

4. Issue PUT-locate. 

5. Move the short record into the buffer segment. 

• Su bstitute mod e ; Move mode is used when substitute mode is 
requested in MVS. 

Two processing modes of the PUTX macro instruction can be used 
in conjunction with a GET-locate macro instruction. The update 
mode returns an updated record to the data set from which it was 
read; the output mode transfers an updated record to an output 
data set. There is no actual movement of data in virtual 
storage. The processing mode is specified by the operand of the 
PUTX macro instruction# as explained in QS/VS2 MVS Data 
Management Macro Instructions . 

If you use the basic access technique# you can control buffers 
in one of two ways 1 

• Directly, using the GETBUF macro instruction to retrieve a 
buffer constructed as described above. A buffer can then be 
returned to the pool by the FREEBUF macro instruction. 

• Dynamically# by requesting a dynamic buffer in your READ or 
WRITE macro instruction. This technique can be used only 
when you are using BISAM or BDAM. If you request dynamic 
buffering# the system automatically provides a buffer each 
time a READ macro instruction is issued. The buffer is 
supplied from a buffer pool that is created by the system 
when the data set is opened. The buffer is released 
(returned to the pool) upon completion of a WRITE macro 
instruction when you are updating. If you do not update the 
record in the buffer and thus release the buffer when the 
record is written# the FREEDBUF macro instruction may be 
used. If you are processing an indexed sequential data set# 
the buffer is automatically released upon the next issuance 
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of the READ macro instruction if there has been no 
intervening WRITE or FREEDBUF macro instruction. 


Simple Buffering 

The term simple buffering refers to the relationship of segments 
within the buffer. All segments in a simple buffer are together 
in storage and are always associated with the same data set. 

When the buffer pool is constructed, the system creates a 
channel command word (COW) for each buffer in the buffer pool. 
For this reason, each record must be physically moved from an 
input buffer segment to an output buffer segment. It can be 
processed within either segment or in a work area. 

If you use simple buffering, records of any format can be 
processed. New records can be inserted and old records deleted 
as required to create a new data set. A record can be moved and 
processed as follows • 

• Processed in an input buffer and then moved to an output 
buffer (GET-locate, PUT-move/PUTX-output) 

• Moved from an input buffer to an output buffer where it can 
be processed (GET-move, PUT-locate) 

• Moved from an input buffer to a work area where it can be 
processed and then moved to an output buffer (GET-move, 
PUT-move) 

• Processed in an input buffer and returned to the data set 
(GET-locate, PUTX-update) 

The following examples illustrate the control of simple buffers 
and the processing modes that can be used. The buffer pools may 
have been constructed in any way previously described. 

Simple Buffering—GET-locate, PUT-move/PUTX-output: The GET 
macro instruction (step A, Figure 33) locates the next input 
record to be processed. Its address is returned in register 1 by 
the system. The address is passed to the PUT macro instruction 
in register 0. 
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GET 



NEXTREC GET 

LR 

PUT 

B 

INDCB DCB 
OUTDCB DCB 


INDCB 

0,1 

OUTDCB,(0 ) 
NEXTREC 

MACRF=(GL),- 

MACRF=(PM),- 


Figure 33. Simple Buffering with MACRF=GL and MACRF=PM 


The PUT macro instruction (step B, Figure 33) specifies the 
address of the record in register 0. The system then moves the 
record to the next output buffer. 

Note: The PUTX-output macro instruction can be used in place of 
the PUT-move macro instruction. However, processing will be as 
described under exchange buffering (see PUT-substitute). 

Simple Buffering—GET-move, PUT-locate: The PUT macro 
instruction locates the address of the next available output 
buffer. Its address is returned in register 1 and is passed to 
the GET macro instruction in register 0. 

The GET macro instruction specifies the address of the output 
buffer into which the system moves the next input record. 

A filled output buffer is not written until the next PUT macro 
instruction is issued. 

simple Buffering—GET-move, PUT-move: The GET macro instruction 
(step A, Figure 34) specifies the address of a work area into 
which the system moves the next record from the input buffer. 
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INDCB,WORKAREA 
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MACRF=(GM ),--~ 
MACRF=(PM),--- 


Figure 34. Simple Buffering with MACRF=GM and MACRF=PM 


The PUT macro instruction (step B> Figure 34) specifies the 
address of a work area from which the system moves the record 
into the next output buffer. 


Simple Buffering—GET-locate, PUT-locate: The GET macro 
instruction (step A, Figure 35) locates the address of the next 
available input buffer. The address is returned in register 1. 



GET 


INPUT 


INPUT 


OUTPUT 


OUTPUT 


PUT 


INPUT 


INPUT 


OUTPUT 


OUTPUT 



NEXTREC 

GET 

INDCB 


LR 

7,1 


PUT 

OUTDCB 


LR 

6,1 


LA 

5, INDCB 


USING 

IHADCB,5 


LH 

4,DCBLRECL 


SH 

4 , =H ' 1 ' 


EX 

4,MOVEREC 


B 

NEXTREC 

MOVEREC 

MVC 

0( 1,6),0(7) 

INDCB 

DCB 

MACRF=( GL), 
EODAD=EOF,- 

OUTDCB 

DCB 

MACRF=( PL), 


DCBD 

DSORG=( LR) 

EOF 

• • • 



Figure 35. Simple Buffering with MACRF=GL and MACRF=PL 


The PUT macro instruction (step B, Figure 35) locates the 
address of the next available output buffer. Its address is 
returned in register 1. You must then move the record from the 
input buffer to the output buffer (step C, Figure 35). 
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Processing can be done either before or after the move 
operation. 

A filled output buffer is not written until the next PUT macro 
instruction is issued. The CLOSE and FEOV macro instructions 
write the last record of your data set by issuing TRUNC and PUT 
macro instructions. Be careful not to issue an extra PUT before 
issuing CLOSE or FEOV. Otherwise, when the CLOSE or FEOV macro 
instruction tries to write your last record, the extra PUT will 
write a meaningless record or produce a sequence error. 

Note that if records other than format-F records are being 
moved, the length attribute of the MVC instruction must be 
changed as shown by the code beginning with the USING statement 
in Figure 35. If the record is more than 256 bytes, you can code 
a move routine or use a MVCl instruction to process the complete 
record. 

SIMPLE BUFFERING-UPDAT MODE: When a data set is opened with 
UPDAT specified (Figure 36), only GET-locate and PUTX-update are 
supported. The GET macro locates the next input record to be 
processed and its address is returned in register 1 by the 
system. The user may update the record and issue a PUTX macro 
which will cause the block to be written back in its original 
location in the data set after all the logical records in that 
block have been processed. 




OPEN 

( UPDCB,(UPDAT ) ) 

NEXTREC 

GET 

UPDCB 


PUTX 

UPDCB 


B 

NEXTREC 

UPDCB 

DCB 

MACRF=(GL,PM),- 


(No movement of data takes place) 


Figure 36. Simple Buffering with MACRF=GL and MACRF=PM-UPDAT Mode 


Exhange Buffering 

Exchange buffering is not supported in MVS. Its request is 
ignored by the system and move mode is used instead. 

BUFFERING TECHNIQUES AND GET/PUT PROCESSING MODES: As you can 

see from the previous examples, the most efficient code is 
achieved by use of automatic buffer pool construction, and 
GET-locate and PUTX-output with simple buffering. Figure 37 
summarizes the combinations of buffering techniques and 
processing modes that can be used. 
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Figure 37 . 


Buffering 


Technique and 


GET/PUT Processing Modes 


RELSE—Release an Input Buffer 


When using the queued access technique to process a sequential 
or indexed sequential data set, you can direct the system to 
ignore the remaining records in the input buffer being 
processed. The next GET macro instruction retrieves a record 
from another buffer. If format-V spanned records are being used, 
the next logical record obtained may begin on any segment in any 
subsequent block. 

If you are using move mode, the buffer is made available for 
refilling as soon as the RELSE macro instruction is issued. When 
you are using locate mode, the system does not refill the buffer 
until the next GET macro instruction is issued. If a PUTX macro 
instruction has been used, the block is written before the 
buffer is refilled. 


TRUNC—Truncate an Output Buffer 


When using the queued access technique to process a 
data set, you can direct the system to write a short 
first record in the next buffer is the next record p 
a PUT-output or PUTX-output mode. 

If the locate mode is being used, the system assumes 
record has been placed in the buffer segment pointed 
last PUT macro instruction. 


sequential 
block. The 
rocessed by 


that a 
to by the 
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The last block of a data set is truncated by the Close routine. 
Note that a data set containing format-F records with truncated 
blocks cannot be read from direct-access storage as efficiently 
as a standard format-F data set. 


GETBUF—Get a Buffer from a Pool 

The GETBUF macro instruction can be used with the basic access 
technique to request a buffer from a buffer pool constructed by 
the BUILD, GETPOOL, or OPEN macro instruction. The address of 
the buffer is returned by the system in a register you specify 
when you issue the macro instruction. If no buffer is available> 
the register contains 0 instead of an address. 


FREEBUF—Return a Buffer to a Pool 

The FREEBUF macro instruction is used with the basic access 
technique to return a buffer to the buffer pool from which it 
was obtained by a GETBUF macro instruction. Although the buffers 
need not be returned in the order in which they were obtained, 
they must be returned when they are no longer needed. 


FREEDBUF—Return a Dynamic Buffer to a Pool 

Any buffer obtained through the dynamic buffer option must be 
released before it can be used again. When you are processing a 
direct data set, if you do not update the block in the buffer 
and thus free the buffer when the block is written, you must use 
the FREEDBUF macro instruction. If there is an uncorrectable 
input/output error, the control program releases the buffer. 

When you are processing an indexed sequential data set, if you 
do not update the block in the buffer or if there is an 
uncorrectable input error, the control program releases the 
buffer when the next READ macro instruction is issued on the 
same DECB, unless you use the FREEDBUF macro instruction. 

To effect the release, you must specify the address of the DECB 
that was used when the block was read using the dynamic 
buffering option, as well as the address of the DCB associated 
with the data set being processed. 


PROCESSING A SEQUENTIAL DATA SET 


Data sets residing on all volumes other than direct-access 
volumes must be processed sequentially. In addition, a data set 
residing on a direct-access volume, regardless of organization, 
can be processed sequentially. This includes data sets created 
using ISAM or a similar access method. Since the entire data set 
(prime, index, and overflow areas) will be processed, care 
should be taken to determine the type of records being 
processed. This feature of the operating system allows you to 
write your program with little regard for the type of device to 
be used when the program is executed, except for restrictions on 
the use of certain device-dependent macro instructions and 
processing options. 

Either the queued or the basic access technique may be used to 
store and retrieve the records of a sequential data set. 
Additionally, a technique called chained scheduling can be used 
to accelerate the input/output operations required for a 
sequential data set (residing on nondirect-access devices for 
5740-AM3). 
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DATA FORMAT—DEVICE TYPE CONSIDERATIONS 


Before execution of your program, you must supply the operating 
system with both the record format (RECFM) and device-dependent 
(DEVD) information in a DCB macro instruction, a DD statement, 
or a data set label. The DCB subparameters for the DD statement 
differ slightly from those described here. A complete 
description of the DD statement and a glossary of DCB 
subparameters are contained in 0S/VS2 JCL . 

The record format (RECFM) parameter of the DCB macro instruction 
specifies the characteristics of the records in the data set as 
fixed-length (RECFM=F), variable-length (RECFM=V or D), or 
undefined-length (RECFM=U). Fixed-length blocked records 
(RECFM=FB) can be specified as standard (RECFM=FBS), which means 
there are no truncated (short) blocks or unfilled tracks within 
the data set, with the possible exception of the last block or 
track. Data sets with a fixed-length, standard format were 
described previously under "Fixed-Length Records, Standard 
Format." 

As an optional feature, a control character can be contained in 
each record. This control character will be recognised and 
processed if the data set is printed or punched. The control 
characters are transmitted on both tapes and direct-access 
volumes. The presence of a control character is indicated by M 
or A in the RECFM field of the data control block. M denotes 
machine code; A denotes American National Standards Institute 
(ANSI) code. If either M or A is specified, the character must 
be present in every record; the printer space (PRTSP) or stacker 
select (STACK) field of the DCB is ignored. The optional control 
character must be in the first byte of format-F and format-U 
records and in the fifth byte of format-V records and format-D 
records where BUF0FF=L. Control character codes are listed in 
"Appendix B: Control Characters." The device-dependent (DEVD) 
parameter of the DCB macro instruction specifies the type of 
device on which the data set’s volume resides 1 

TA magnetic tape 

PT paper tape reader 

PR printer 

PC card punch 

RD card reader 

DA direct-access device or 

Mass Storage System (MSS) virtual volumes 


Magnetic Tape (TA) 

Format-F, V, D, and U records are acceptable for magnetic tape. 
Format-V records are not acceptable on 7-track tape if the data 
conversion feature is not available. ASCII records are not 
acceptable on 7-track tape. 

When you create a tape data set with variable-length record 
format (V or D), the control program pads any data block shorter 
than 18 bytes. For format-V records, it pads to the right with 
binary zeros so that the data block length equals 18 bytes. For 
format-D (ASCII) records, the padding consists of ASCII 
circumflex characters which are equivalent to X’5E's. 

Note that there is no minimum requirement for blocksize; 
however, if data check occurs on a magnetic-tape device, any 
record shorter than 12 bytes in a read operation or 18 bytes in 
a write operation will be treated as a noise record and lost. No 
check for noise will be made unless a data check occurs. 

Tape density (DEN) specifies the recording density in bits per 
inch per track, as shown in Figure 38. If this information is 
not supplied, the highest applicable density is assumed. 
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Recording Density 

DEN 7-Track Tape 9-Track Tape 

0 200 - 

1 556 

2 800 800 CNRZI) 

3 - 1600 (PE) 

4 — 6250 (GCR) 

NRZI is for non-return-to-zero-inverted mode 

PE is for phase encoded mode 

GCR is for group coded recording mode 

Specifying DEN = 0 for a 7-track 3420 tape attached to a 3803-1 
will result in 556 bits per inch recording, but corresponding 
messages and tape labels will indicate 200 bits per inch 
recording density. 

Figure 38. Tape Density (DEN) Values 


The track recording technique (TRTCH) for 7-track tape can be 

specified as : 

C Data conversion is to be used. Data conversion makes it 
possible to write 8 binary bits of data on 7 tracks. 
Otherwise, only 6 bits of an 8-bit byte are recorded. The 
length field of format-V records contains binary data and is 
not recorded correctly without data conversion. 

E Even parity is to be used; if E is omitted, odd parity is 
assumed. 

T BCDIC to EBCDIC translation is required. 


Paper-Tape Reader (PT) 

The paper-tape reader accepts format-F and format-U records. If 
you use QSAM, you should not specify the records as blocked. 

Each format-U record is followed by an end-of-record character. 
Data read from paper tape may optionally be converted into the 
System/370 internal representation of one of six standard 
papei—tape codes. Any character found to have a parity error 
will not be converted when the record is transferred into the 
input area. Characters deleted in the conversion process are not 
counted in determining the block size. 

The following symbols indicate the code in which the data was 
punched. If this information is omitted, I is assumed. 

I IBM BCD perforated tape and transmission code (8 tracks) 

F Friden (8 tracks) 

B Burroughs (7 tracks) 

C National Cash Register (8 tracks) 

A ASCII (8 tracks) 

T Teletype 1 (5 tracks) 

N No conversion 

Note that when you are using QSAM, the processing mode must be 
move mode. 


Trademark of the Teletype Corporation 
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Card Reader and Punch (RD/PC) 

Format-F and U records are acceptable to both the reader and 
punch; format-V records are acceptable to the punch only. The 
device control character, if specified in the RECFM parameter, 
is used to select the stacker; it is not punched. The first 4 
bytes (record descriptor word or segment descriptor word) of 
format-V records or record segments are not punched. For 
format~V records, at least 1 byte of data must follow the record 
or segment descriptor word or the carriage control character. 

Each punched card corresponds to one physical record. Therefore, 
you should restrict the maximum record size to 80 (EBCDIC mode) 
or 160 (column binary mode) data bytes. When mode (C) is used 
for the card punch, BLKSIZE must be 160 unless you are using 
PUT. Then you can specify BLKSIZE as 160 or a multiple of 160, 
and the system handles this as described earlier under 
"PUT—Write a Record" in the section "Queued Access Techniques." 
You can specify the read/punch mode of operation (NODE) 
parameter as either card image (column binary) mode (C) or 
EBCDIC mode (E). If this information is omitted, E is assumed. 
The stacker selection parameter (STACK) can be specified as 
either 1 or 2 to indicate which bin is to receive the card. If 
it is not specified, 1 is assumed. 

For all QSAN, RECFM=FB, card punch data sets, the block size in 
the DCB will be adjusted by the system to equal the logical 
record length. This data set will be treated as RECFM=F. If the 
system builds the buffers for this data set, the buffer length 
will be determined by the BUFL parameter.. If the BUFL parameter 
was not specified, the adjusted block size is used for the 
buffer length. 

If the DCB is to be reused with a block size larger than the 
logical record length, you must reset DCBBLK5I in the DCB and 
ensure that the buffers are large enough to contain the largest 
block size expected. You may ensure the buffer size by 
specifying the BUFL parameter before the first time the data set 
is opened or by issuing the FREEPOOL macro instruction after 
each CLOSE macro so the system will build a new buffer pool of 
the correct size each time the data set is opened. 

Punch error correction on the IBN 2540 Card Read Punch is not 
performed when using MVS. 

The 3525 Card Punch accepts only format-F records for print data 
sets and for associated data sets. Other record formats are 
allowed for the read data set, the punch data set, and the 
interpret punch data set. See OS and QS/VS Programming Support 
for the IBM 3505 Card Reader and IBN 3525 Card Punch for more 
information on programming for the 3525 Card Punch. 


Printer (PR) 

Records of format-F, V, and U are acceptable to the printer. The 
first 4 bytes (record descriptor word or segment descriptor 
word) of format-V records or record segments are not printed. 

For format-V records, at least 1 byte of data must follow the 
record or segment descriptor word or the carriage control 
character. The carriage control character, if specified in the 
RECFM parameter, is not printed. The system does not position 
the printer to channel 1 for the first record unless specified 
by a carriage control character. 

Because each line of print corresponds to one record, the record 
length should not exceed the length of one line on the printer. 
For variable-length spanned records, each line corresponds to 
one record segment, and blocksize should not exceed the length 
of one line on the printer. 

If carriage control characters are not specified, you can 
indicate printer spacing (PRTSP) as 0, 1, 2, or 3. If it is not 
specified, 1 is assumed. 
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For all QSAM, RECFM=FB, printer data sets, the block size in the 
DCB will be adjusted by the system to equal the logical record 
length. This data set will be treated as RECFM=F. If the system 
builds the buffers for this data set, the buffer length will be 
determined by the BUFL parameter. If the BUFL parameter was not 
specified, the adjusted block size is used for the buffer 
length. 

If the DCB is to be reused with a block size larger than the 
logical record length, you must reset DCBBLKSI in the DCB and 
insure that the buffers are large enough to contain the largest 
block size expected. You may insure the buffer size by 
specifying the BUFL parameter before the first time the data set 
is opened or by issuing the FREEPOOL macro instruction after 
each CLOSE macro so the system will build a new buffer pool of 
the correct size each time the data set is opened. 


Direct-Access Device (DA] 

Direct-access devices accept records of format-F, V, or U. If 
the records are to be read or written with keys, the key length 
(KEYLEN) must be specified. In addition, the operating system 
has a standard track format for all direct access volumes. Each 
track contains data information as well as certain control 
information such as: 

• The address of the track 

• The address of each record 

• The length of each record 

• Gaps between areas 

A complete description of track format is contained in the 
section "Direct-Access Device Characteristics." Your only 
concern in creating a sequential data set is to allow for an 
8-byte track descriptor record (capacity record or RO) when 
requesting space on a direct-access volume. In addition, device 
overhead, which varies with the device, must be allocated for 
each block on the track. 


DEVICE CONTROL 


The operating system provides you with six macro instructions 
for controlling input/output devices. Each is, to varying 
degrees, device-dependent. Therefore, you must exercise some 
care if you wish to achieve device independence. 

When you use the queued access technique, only unit record 
equipment can be controlled directly. When using the basic 
access technique, limited device independence can be achieved 
between magnetic-tape and direct-access devices. You must check 
all read or write operations before issuing a device control 
macro instruction. 


CNTRL—Control an I/O Device 

The CNTRL macro instruction performs these device-dependent 
control functions^ 

• Card reader stacker selection (SS) 

• Printer line spacing (SP) 

• Printer carriage control (SK) 

• Magnetic-tape backspace (BSR) over a specified number of 

blocks 
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• Magnetic-tape backspace (BSM) past a tapemark and forward 
space over the tapemark 

• Magnetic-tape forward space (FSR) over a specified number of 
blocks 

• Magnetic-tape forward space (FSM) past a tapemark and a 
backspace over the tapemark 

Backspacing moves the tape toward the load point; forward 
spacing moves the tape away from the load point. 

Note that the CNTRL macro instruction cannot be used with an 
input data set containing variable-length records on the card 
reader. 

You can use the CNTRL macro instruction to position DOS tapes 
that contain embedded DOS checkpoint records if you specify 
0PTCD=H in the DCB parameter field of the DD statement. The 
CNTRL macro instruction cannot be used to backspace DOS 7-track 
tapes that are written in data convert mode and contain embedded 
checkpoint records. 


PRTOV—Test for Printer Overflow 

The PRTOV macro instruction tests for channel 9 or 12 of the 
printer carriage control tape or the forms control buffer (FCB). 
An overflow condition causes either an automatic skip to channel 
1 or, if specified, transfer of control to your routine for 
overflow processing. If you specify an overflow exit routine, 
set DCBIFLGS to X’OO* before issuing another PRTOV. 

If the data set specified in the DCB is not for a printer, no 
action is taken. 


SETPRT—Printer Setup 

The SETPRT macro instruction is used to initially set or 
dynamically change the specifications of the 3800 Printing 
Subsystem. The SETPRT macro instruction is also used to 
dynamically change the specifications of the 3203 or 3211 
printers or the 1403 printer with UCS. For additional 
information on how to use the SETPRT macro with the 3800 
printer, see IBM 3800 Printing Subsystem Programmer's Guide . 

For printers that have a universal character set (UCS) buffer or 
a forms control buffer (FCB), the SETPRT macro instruction is 
used to fetch UCS and FCB images from the image library 
(SY51.IMAGELIB) and load them into their respective buffers. 

Note that FCB images for the 3203, 3211, and 3800 are not 
compatible. The universal character sets for the 1403, 3203, or 
3211 and the character arrangement tables for the 3800 are also 
incompatible. 

The SETPRT macro allows you to request the operator to verify 

loading of the buffer. For the 1403, 3203, and 3211 printers, 

the SETPRT macro allows you to specify the printing of lowercase 

EBCDIC characters in uppercase when no uppercase/lowercase print 

chain or train is available. 

For a printer that has no carriage control tape, you can use the 
SETPRT macro instruction to load the FCB, to request operator 
verification of buffer loading, and to allow the operator to 
align the paper in the printer. 

The FCB contents can be fetched from the system library or 
defined in your program through the exit list of the DCB macro 
instruction, as discussed under "Exit List (EXLST).” 

When issued, the SETPRT macro instruction can load the UCS 
buffer from the system library. The library contains images of 
standard IBM character sets and of your own special character 
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sets. The operator can be requested to verify the loaded image 
after mounting the appropriate print chain or train. 

With 3800 Enhancements, the SETPRT macro can be used to fetch 
3800 load modules from SYS1.IMAGELIB or from an alternate 
library that you specify. 

The SETPRT macro instruction can be used to block or unblock 
printer data checks. When data checks are blocked, unprintable 
characters are treated as blanks and do not cause an error 
condition. 

Except for the 3800, if the specified UCS or FCB image is not 
found in the image library Cor DCB exit list for an FCB image), 
the operator is requested to specify a different one (message 
IEC127D is issued). If the operator is unable to supply a valid 
name, or the device is a 3800, the SETPRT macro will give an 
error return code. 


BSP—Backspace a Magnetic Tape or Direct-Access Volume 

The BSP macro instruction backspaces one block on the magnetic 
tape or direct-access volume being processed. The block can then 
be reread or rewritten. An attempt to rewrite the block destroys 
the contents of the remainder of the tape or track. 

The direction of movement is toward the load point or beginning 
of the extent. You may not use the BSP macro instruction if the 
track overflow option was specified or if the CNTRL, NOTE, or 
POINT macro instruction is used. The BSP macro instruction 
should be used only when other device control macro instructions 
could not be used for backspacing. 

Any attempt to backspace across a file mark will result in a 
return code of X'04' and your tape or direct-access volume will 
be positioned after the file mark. This means you cannot issue a 
successful backspace command once your EODAD routine is entered 
unless you first reposition the tape or direct-access volume 
into your data set. (CLOSE TYPE = T can get you positioned at the 
end of your data set.) 

You can use the BSP macro instruction to backspace DOS tapes 
containing embedded DOS checkpoint records. If you use this 
means of backspacing, you must test for and bypass the embedded 
checkpoint records. You cannot use the BSP macro instruction for 
DOS 7-track tapes written in translate mode. 


NOTE—Return the Relative Address of a Block 

The NOTE macro instruction requests the relative address of the 
block just read or written. In a multivolume data set, the 
address is relative to the beginning of the volume currently 
being processed. 

The address provided by the operating system is returned in 
register 1. The address is in the form of a 4-byte relative 
block address for magnetic tape) for a direct-access device, it 
is a 4-byte relative track address. The amount of unused space 
available on the track of the direct-access device is returned 
in register 0. 


POINT—Position to a Block 

The POINT macro instruction causes repositioning of a magnetic 
tape or direct-access volume to a specified block. The next read 
or write operation begins at this block. In a multivolume data 
set, you must ensure that the volume referred to is the volume 
currently being processed. If a write operation follows the 
POINT macro instruction, all of the track following the write 
operation is erased unless the data set is opened for UPDAT. 
POINT is not meant to be used before a WRITE macro instruction 
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when a data set is opened for UPDAT. You can use the POINT macro 
instruction to position DOS tapes that contain embedded 
checkpoint records if you specify QPTCD=H in the DCB parameter 
field of the DD statement. The POINT macro instruction cannot be 
used to backspace DOS 7-track tapes that are written in data 
convert mode and contain embedded checkpoint records. 

When using the POINT macro for a direct-access device that is 
opened for OUTPUT, OUTIN, or IN0UT> and the record format is not 
standard, the number of blocks per track may vary slightly. 


DEVICE INDEPENDENCE 

The ability to request input/output operations without regard 
for the physical characteristics of the I/O devices makes it 
possible for you to write one program that will fulfill a 
variety of needs. Device independence may be useful fori 

• Accepting data from a number of recording devices, such as a 
disk pack, 7- or 9-track magnetic tape, or unit-record 
equipment. This situation could arise when several types of 
data-acquisition devices are feeding.a centralized complex. 

• Observing constraints imposed by the availability of 
input/output devices (for example, when devices on order 
have not been installed). 

• Assembling, testing, and debugging on one System/370 
configuration and processing on a different configuration. 
For example, a 2314 drive can be used as a substitute for 
several magnetic-tape units. 

Device independence is not difficult to achieve, but requires 
some planning and forethought. There are two areas of planning 
necessary to achieve device independence—system generation 
considerations and programming considerations. 


system Generation Considerations 

You can provide for device independence when the system is 
generated by generating a system that not only meets the current 
input/output configuration requirements but includes anticipated 
device attachments. Creating such a system entails looking ahead 
at expected delivery of input/output devices and, during system 
generation, constructing the necessary control blocks and 
tables. Thus, when the devices are delivered, they need only be 
physically attached. The operating system recognizes the devices 
without modification. However, until the devices are physically 
connected, the operator must designate them as being offline, 
using the VARY command, unless OPTIONSiiDEVSTAT was specified on 
the CTRLPROG macro during system generation. For information on 
the CTRLPROG macro, see 0S/V52 System Programming Library: 

System Generation Reference . 


When new device attachments cannot be fully anticipated, you can 
add new devices by performing an I/O device generation. This is 
a limited type of system generation that enables you to change 
your I/O configuration without regenerating other parts of the 
system. 

System generation techniques for effecting a smooth transition 
to new input/output devices do not include addition of new 
device types. When support for new devices is provided, a new 
system must be generated. A complete description of system 
generation techniques is contained in QS/VS2 System Programming 
Library: System Generation Reference . 
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Programming Considerations 

Each of three data set organizations—partitioned, indexed 
sequential, and direct—requires the use of a direct-access 
device. Device independence is meaningful, then, only for a 
sequentially organized data set, that is, a data set where one 
block of data follows another, thus allowing input or output to 
be on a magnetic tape drive, a direct-access device, a card 
read/punch, a printer, or a spooled data set. 

Your program will be device-independent if you do two things* 

• Omit all device-dependent macro instructions and macro 
instruction parameters from your program. 

• Defer specifying any required device-dependent parameters 
until the program is ready for execution. That is, supply 
the parameters on your data definition (DD) statement or 
during the open exit routine. 

In examining the following list of macro instructions, consider 
only the logical layout of your data record without regard for 
the type'of device used. Also, consider that any reference to a 
direct-access volume is to be treated like a reference to 
magnetic tape, that is, you must create a new data set rather 
than attempt to update. 

OPEN 

Specify INPUT, OUTPUT, INOUT, OUTIN, OUTINX, or EXTEND. 
The parameters RDBACK and UPDAT are device-dependent and 
cause an abnormal termination if directed to a device of 
the wrong type. 

READ 

Specify forward reading (SF) only. 

WRITE 

Specify forward writing (SF) only; use only to create new 
records. 


PUTX 

Use only output mode. 

NOTE/POINT 

These macros are valid for both magnetic-tape and 
direct-access volumes. 


BSP 

This macro is valid for magnetic-tape or direct-access 
volumes. However, its use would be an attempt to perform 
device-dependent action. 

CNTRL/PRTOV 

These macros are device-dependent. 

DCB Subparameters 

MACRF 

Specify R/W or G/P. Processing mode can also be indicated. 

DEVD 

Specify DA if any direct-access device may be used. 
Magnetic-tape and unit-record equipment DCBs will fit in 
the area provided during assembly. Specify unit-record 
devices only if you expect never to change to tape or 
direct-access devices. Key length (KEYLEN) can be specified 
on the DD statement if necessary. 

RECFM, LRECL, BLKSIZE 

These can be specified in the DD statement. However, you 
must consider maximum record size for specific devices, and 
track overflow cannot be specified unless supported. 
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DSORG 


Specify sequential organization CPS or PSU). 

OPTCD 

This subparatneter is device-dependent; specify it in the DD 
statement. 


SYNAD 

Any device-dependent error checking is automatic. 
Generalize your routine so that no device-dependent 
information is required. 


CHAINED SCHEDULING FOR I/O OPERATIONS (INCLUDING NONDIRECT-ACCESS DEVICES FOR 
5740-AM3 ONLY] 


To accelerate the input/output operations required for a data 
set, the operating system provides a technique called chained 
scheduling . When requested, the system bypasses the normal I/O 
routines and dynamically chains several input/output operations 
together. A series of separate read or write operations, 
functioning with chained scheduling, is issued to the computing 
system as one continuous operation. In a nonpageable partition 
or address space, the program-controlled interruption (PCI) flag 
in the CCWs is used for synchronization of the I/O operations. 

The I/O performance is improved by reduction in both the CPU 
time and the channel start/stop time required to transfer data 
within virtual storage. Some factors that affect performance 
improvement are: 

• Address space type (real or virtual) 

• BUFNO for QSAM 

• The number of overlapped requests for BSAM 

• Other activity on the CPU and channel 

The effects of rotational delay are also reduced, since several 
successive blocks, requested separately, can be retrieved in a 
single rotation. Chained scheduling can be used only with simple 
buffering. Each data set for which chained scheduling is 
specified must be assigned at least two and preferably three 
buffers with QSAM, or must have a value of at least two and 
preferably three for NCP with BSAM or BPAM. 

Chained scheduling will be used by MVS whether it is requested 
or not (except for printers and format-U input records). Chained 
scheduling will not be used where it is not allowed. 

For 5740-AM3 the following two paragraphs replace the paragraph 
above • 

The system will default to chained scheduling for 
nondirect-access devices (other than printers and format-U 
records on nondirect-access devices) except for those cases in 
which it is not allowed. 

A request for exchange buffering in MVS is not honored, but 
compatibly defaults to move mode and therefore has no effect on 
either a request for chained scheduling or a default to chained 
scheduling. 

A request for chained scheduling will be ignored and normal 
scheduling used if any of the following are encountered when the 
data set is opened: 

• Direct Access Device (5740-AM3 only) >, 

• Search Direct (This line is deleted by 5740-AM3) 
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• BDAM CREATE, that is, MACRF=(WL) (This line is deleted by 
5740-AM3) 

• Track overflow 

• UPDAT in the operand of the OPEN macro instruction 

• CNTRL macro instruption to be used 

• Device type is paper tape reader 

• Bypassing of embedded DOS checkpoint records on tape input 
data sets 

• Spooled data sets (SYSIN or SYSOUT) 

• A print data set or any associated data set for the 3525 
Card Punch. (See OS and OS/VS Programming Support for the 
IBM 3505 Card Reader and IBM 3525 Card Punch for more 
information on programming for the 3525.) 

The number of channel program segments that can be chained is 
limited to the value specified in the NCP operand of BSAM and 
BPAM DCBs, and to the value specified in the BUFNO operand of 
QSAM DCBs. 

Chained scheduling should not be specified (DCB=OPTCD=C) when 
channel 9 or channel 12 is in the carriage control tape. 

When chained scheduling is being used, the automatic skip 
feature of the PRTOV macro instruction for the printer will not 
function. Format control must be achieved by ANSI or machine 
control characters. (Control characters are discussed in more 
detail in Part 1 under "Control Character,” in Part 2 under 
"Data Format—Device Type Considerations," and in "Appendix B* 
Control Characters.") When you read undefined-length records 
with QSAM, the DCBLRECL field is equal to the BLKSIZE field, not 
the actual record length. The entire block is moved to your work 
area in the move mode. When you are using QSAM under chained 
scheduling to read variable-length, blocked, ASCII tape records 
(format-DB), you must code BUF0FF=L in the DCB for that data 
set. 

Note also that if you are using BSAM with the chained scheduling 
option to read format-DB records and have coded a value for the 
BUFOFF operand other than BUF0FF=L, the input buffers will be 
converted from ASCII to EBCDIC as usual, but the record length 
returned to the DCBLRECL field will equal the block size, not 
the actual length of the record read in; the record descriptor 
word (RDW), if present, will not have been converted from ASCII 
to binary. 

A request for the chained scheduling technique overrides a 
request for the search direct technique. If you request both 
techniques, or if chained scheduling is defaulted and search 
direct is requested, then chained scheduling is used. 

Chained scheduling is most valuable for programs that require 
extensive input and output operations. Because a data set using 
chained scheduling may monopolize available time on a channel in 
a V=R region, separate channels should be assigned; if possible, 
when more than one data set is to be processed. 


SEARQH DIRECT FOR INPUT OPERATIONS (EXCEPT 5740-AM3) 

To accelerate the input operations required for a data set on 
DASD, the operating system provides a technique called search 
direct . Search direct reads in the requested record and the 
count field of the second record. This allows the operation to 
get the next record directly, along with the count field of the 
following record. Search direct can be used with all record 
formats except format-UT, format-FBT, format-FS, format-FBS, and 
spanned. You request search direct by coding 0PTCD=Z in the DCB 
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macro instruction. For FS and FBS records, the access method 
routines always use a form of search-direct processing. Search 
direct cannot be used under the following conditions: 


• In conjunction with the NOTE and POINT macro instructions 

• When you specify the UPDAT option of the OPEN macro 
instruction 

• For partitioned data sets 

• When chained scheduling is used 


SEARCH DIRECT FOR INPUT OPERATIONS C5740-AM3 ONLY) 

To accelerate the input operations required for a data set on 
DASD, the operating system provides a technique called search 
direct ♦ Search direct reads in the requested record and the 
count field of the second record. This allows the operation to 
get the next record directly, along with the count field of the 
following record. 

The function provided by the search-direct option is supplied 
whether or not it is requested. OPTCD=Z need not be coded and if 
used is ignored. 

Except under the following conditions: 

• In conjunction with the NOTE and POINT macro instructions 

• When you specify the UPDAT option of the OPEN macro 
instruction 

• For partitioned data sets 

• When chained scheduling is used 

you may receive unpredictable results when your application runs 
on a system with the Sequential Access Method-Extended (SAM-E) 
installed and your application has a dependency that prevents 
the use of search direct. For example, you may receive 
unpredictable results when multiple DCBs are open for a file and 
one of the applications is updating or adding records. 


CREATING A SEQUENTIAL DATA SET 

As discussed earlier, a processing program should be developed 
using, as much as possible, factors that are constant, with 
variable factors specified at execution. For that reason, the 
following examples are generalized as much as possible. They are 
neither exhaustive nor intended as complete examples. Rather, 
they are presented as introductory sequences. 


In creating a sequential data set on a magnetic tape or 
direct-access device, you must do the following: 


• Code DS0RG=PS or PSU in the DCB macro instruction 

• Code a DD statement to describe the data set (See QS/VS2 
JCL . ) 


• Process the data set with an OPEN macro instruction (data 

set is opened for output or OUTIN), a series of PUT or WRITE 
and CHECK macros, and then a CLOSE macro 

TAPE-TO-PRINT, MOVE MODE—SIMPLE BUFFERING: In Figure 39, the 
GET-move and PUT-move require two movements of the data records. 
If the record length (LRECL) does not change in processing, only 
one move is necessary; you can process the record in the input 
buffer segment. A GET-locate can be used to provide a pointer to 
the current segment. 
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OPEN 

(INDATA,,OUTDATA, 

(OUTPUT)) 

NEXTREC 

GET 

INDATA,WORKAREA 

Move mode 


AP 

NUMBER,=P»1 * 



UNPK 

COUNT,NUMBER 

Record count adds 6 


PUT 

OUTDATA,COUNT 

bytes to each record 


B 

NEXTREC 


TAPERROR 

SYNADAF 

ACSMETH=QSAM 

Control program returns 


LA 

0,68(0,1) 

message address in register 1 


ST 

14,SAVE14 

SYNAD routine prints part of 


PUT 

OUTDATA,(0) 

the message (beginning with 


SYNADRLS 


the unit number) as a 56-byte 


L 

14,SAVE14 

fixed-length record. It then 


RETURN 


returns to the control 

ENDJOB 

CLOSE 

(INDATA,,OUTDATA) 

program. 

WORKAREA 

DS 

CL50 


COUNT 

DS 

CL6 


NUMBER 

DC 

PL4'0 ’ 


SAVE14 

DS 

F 


INDATA 

DCB 

DDNAME=INPUTDD,DSORG=PS,MACRF=(GM),ER0PT=ACC, C 


SYNAD = T APERROR,E0DAD = 

ENDJOB 

OUTDATA 

DCB 

DDNAME=OUTPUTDD,DSORG=PS,MACRF=(PM),ER0PT=ACC 

Figure 39 

. Creati 

ng a Sequential Data Set—Move Mode, Simple Buffering 


TAPE-TO-PRINT, LOCATE MODE—SIMPLE BUFFERING: This example 
(Figure 40) is similar to that in Figure 39. However, since 
there is no change in the record length, the records can be 
processed in the input buffer. Only one move of each data record 
is required. 


RETRIEVING A SEQUENTIAL DATA SET 

In retrieving a sequential data set on a magnetic tape or 

direct-access device, you must do the following: 

• Code DS0RG=PS or PSU in the DCB macro instruction 

• Tell the system where your data set is located (by coding a 
DD statement; see Q5/VS2 JCL ). 

• Process the data set with an OPEN macro instruction (data 
set is opened for input, INOUT, RDBACK, or UPDAT), a series 
of GET or READ macros and then a CLOSE macro. 

• PURGE HALT I/O should not be used to terminate outstanding 
I/O from READ or GET macros if you intend to continue 
reading records from the data set after the PURGE. The 
results are unpredictable and can result in a wait state if 
you are using chained scheduling or Sequential Access 
Method-Extended (SAM-E), 5740-AM3. 
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OPEN 

(INDATA,,OUTDATA,(OUTPUT),ERRORDCB,(OUTPUT)) 

NEXTREC 

GET 

INDATA 

Locate mode 


LR 

2,1 

Save pointer 


AP 

NUMBER,=P’l’ 



UNPK 

0(6,2),NUMBER 

Process in input area 


PUT 

OUTDATA 

Locate mode 


MVC 

0(50,1),0(2) 

Move record to output buffer 


B 

NEXTREC 


TAPERROR 

SYNADAF 

ACSMETH=QSAM 

Message address in register 1 


ST 

2,SAVE2 

Save register 2 contents 


L 

2,8(0,1) 

Load pointer to input buffer 


MVC 

8(70,1),50(1) 

Shift nonblank message fields 


MVI 

78(1),C» ' 

Blank end of message 


MVC 

79(49,1),78(1) 



ST 

2,128(1) 

Save address for debugging 


CH 

0,=H'4' 

Test SYNADAF return code 


BE 

MOVERCD 

Branch if data read 


BL 

PRINTIT 

Branch if data not read 


CLI 

128(1),C' * 

See if data read anyway 


BE 

PRINTIT 

Branch if definitely no data 

MOVERCD 

MVC 

78(50,1),0(2) 

Add input record to message 

PRINTIT 

LA 

0,4(1) 

Load address of message 


LR 

2,14 

Save return address 


PUT 

ERRORDCB,(0) 

Print message (move mode) 


SYNADRLS 


Release message and save area 


LR 

14,2 

Restore return address 


L 

2, SAVE2 

Restore register 2 contents 


RETURN 


Return to control program 

ENDJOB 

CLOSE 

(INDATA,,OUTDATA,,ERRORDCB) 

NUMBER 

DC* 

PL4’0' 


INDATA 

DCB 

DDNAME=INPUTDD,DSORG=PS,MACRF=(GL),EROPT=ACC, C 


SYNAD=TAPERROR,E0DAD=ENDJ0B 


OUTDATA 

DCB 

DDNAME=OUTPUTDD,DS0RG= 

PS/MACRF=(PL) 

ERRORDCB 

DCB 

DDNAME=SYSOUTDD,DSORG= 

PS,MACRF=(PM),RECFM=V, C 

BLKSIZE=128,LRECL=124 


SAVE2 

DS 

F 


Figure 40 

. Creating 

a Sequential Data Set- 

—Locate Mode, Simple Buffering 


UPDATING A SEQUENTIAL DATA SET 

When you update in place, you read records, process them, and 
write them back to their original positions without destroying 
the remaining records on the track. The following rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro 
instruction. To perform the update, you can use only the 
READ, WRITE, CHECK, NOTE, POINT, GET, and PUTX macro 

instructions. 

• You cannot use chained scheduling. 

• You cannot delete any record or change its length; you 
cannot add new records. 

• The data set must be on a direct-access device. 

A record must be retrieved by a READ or GET macro instruction 
before it can be updated by a WRITE or PUTX macro instruction. A 
WRITE or PUTX macro instruction does not need to be issued after 
each READ or GET macro instruction. The READ and WRITE macro 
instructions must be execute forms that refer to the same DECB; 
the DECB must be provided by the list forms of the READ or WRITE 
macro instructions. (The execute and list forms of the READ and 
WRITE macro instructions are described in 0S/VS2 MVS Data 
Management Macro Instructions .) 
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UPDATING WITH OVERLAPPED OPERATIONS: To overlap input/output and 
CPU activity* you can start several read or write operations 
before checking the first for completion. You cannot overlap 
read with write operations, however, as operations of one type 
must be checked for completion before operations of the other 
type are started or resumed. Note that each concurrent read or 
write operation requires a separate channel program and a 
separate DECB. If a single DECB were used for successive read 
operations, only the last record read could be updated. 

In Figure 50, overlap is achieved by having a read or write 
request outstanding while each record is being processed. Note 
the use of the execute and list forms of the READ and WRITE 
macro instructions, identified by the operands MF = E and MF r L. 


EXTENDING A SEQUENTIAL DATA SET 

If you want to add records at the end of your data set, you must 
open the data set for output with DISP=M0D specified in the DD 
statement or specify the EXTEND option of the OPEN macro. You 
can then issue PUT or WRITE macros to the data set. 


DETERMINING THE LENGTH OF A RECORD WHEN USING THE BSAM READ MACRO 

When you read a sequential data set, you can determine the 
length of the record in one of the following four ways, 
depending upon the record format of the data set: 

• For fixed-length, unblocked records, the length of all 
records is the value in the DCBBLKSI field of the DCB. 

• For variable-length records, the block descriptor word in 
the record contains the length of the record. 

• For fixed-length blocked or undefined-length records, the 
following method can be used to calculate the block length. 
(This method should.not be used when reading track overflow 
records on a device with the rotational position sensing 
(RPS) feature or when using chained scheduling with format U 
records. In these cases, the length of a record cannot be 
determined.) (For 5740-AM3 only, this method should not be 
used for chained scheduling on non-direct access devices. 

The length of a record cannot be determined when using 
chained scheduling.) After checking the DECB for the READ 
request but before issuing any subsequent data management 
macro instructions that specify the DCB for the READ 
request, obtain the IQB address from the DECB. The IOB 
address can be loaded from the location 16 bytes from the 
start of the DECB. 

Obtain the residual count from the channel status word (CSW) 
that has been stored in the input/output block (IOB). The 
residual count is in the halfword 14 bytes from the start of 
the IOB. Subtract this residual count from the number of 
data bytes requested to be read by the READ macro 
instruction. If ”S” was coded as the length parameter of the 
READ macro instruction, the number of bytes requested is the 
value of DCBBLKSI at the time the READ was issued. If the 
length was coded in the READ macro instruction, this value 
is the number of data bytes and it is contained in the 
halfword 6 bytes from the beginning of the DECB. The result 
of the subtraction is the length of the block read. See 
Figure 41. 
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OPEN 

(DCB,(INPUT)) 


LA 

DCBR,DCB 


USING 

IHADCB,DCBR 


READ 

DECB1,SF,DCB,AREA1,'S* 


READ 

DECB2,SF,DCB,AREA2,50 


CHECK 

DECB1 


LH 

W0RK1,DCBBLKSI 

Block size at time of READ 

L 

W0RK2,DECB1+16 

IOB address 

SH 

W0RK1,14(W0RK2) 

W0RK1 has block length 

CHECK 

DECB2 


LH 

WORK 1,DECB2 + 6 

Length requested 

L 

W0RK2,DECB2+16 

IOB address 

SH 

W0RK1,14(W0RK2) 

W0RK1 has block length 

MVC 

DCBBLKSI,LENGTH3 

Length to be read 

READ 

DECB3,SF,DCB,AREA3 


CHECK 

DECB3 


LH 

W0RK1,LENGTH3 

Block size at time of READ 

L 

W0RK2,DECB+16 

IOB address 

SH 

W0RK1,14(W0RK2) 

W0RK1 has block length 

DCB DCB 

. . .RECFM=U,NCP = 2>... 


DCBD 



Figure 41. One 

Method of Determining the Length 

of the Record When Using BSAM 

to 

Read Undefined-Length Records 



Except for 5740-AM3, for undefined-length records, the LRECL 
operand should be omitted; the actual length can be supplied 
dynamically in a READ/WRITE macro instruction. (This method 
should not be used when reading track overflow records on a 
device with the rotational position sensing (RPS) feature or 
when using chained scheduling on any device.) When an 
undefined-length record is read, the actual length of the 
record is returned by the system in the DCBLRECL field of 
the data control block. 

For 5740-AM3, when an undefined-length record is read, the 
actual length of the record is returned in the DCBLRECL 
field of the data control block. Because of this use of 
DCBLRECL, the LRECL operand should be omitted. The length to 
be read or written can be supplied dynamically in a 
READ/WRITE macro instruction using BSAM. This method cannot 
be used when using chained scheduling on any non-direct 
access device. 


WRITING A SHORT BLOCK WHEN USING THE BSAM WRITE MACRO 

When you are writing blocks for a sequential data set, you can 
change the length of a block if you have fixed-blocked record 
format. The DCB block size field (DCBBLKSI) can be changed to 
specify a block size that is shorter than what was originally 
specified for the data set. The DCBBLKSI field must be changed 
before issuing the WRITE macro instruction and must be a 
multiple of the LRECL parameter in the DCB. Any subsequent WRITE 
macro instructions issued will write records with the new block 
length until the block size is changed again. The DCB block size 
field should not be changed to specify a block size that is 
greater than what was originally specified for the data set. 
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PROCESSING A PARTITIONED DATA SET 


( 

A partitioned data set can be stored only on a direct-access v 

device. It is divided into sequentially organized members ? each 
made up of one or more records (see Figure 42). Each member has 
a unique name, 1 to 8 characters long, stored in a directory 
that is part of the data set. The records of a given member are 
stored or retrieved sequentially. 



Space from 

Deleted 

Member 


Available 

Area 


Figure 42. A Partitioned Data Set 


The main advantage of using a partitioned data set is that you 
can retrieve any individual member once the data set is opened 
without searching the entire data set. For example, a program 
library can be stored as a partitioned data set, each member of 
which is a separate program or subroutine. The individual 
members can be added or deleted as required. When a member is 
deleted, the member name is removed from the directory, but the 
space used by the member cannot be reused until the data set is 
reorganized. 

The directory, a series of records at the beginning of the data 
set, contains an entry for each member. Each directory entry 
contains the member name and the starting location of the member 
within the data set, as shown in Figure 42. In addition, you can 
specify up to 62 characters of information in the entry. The 
directory entries are arranged in alphameric collating sequence 
by name. 

The track address of each member is recorded by the system as a 
relative track address within the data set rather than as an 
absolute track address. Thus, an entire data set can be moved 
without changing the relative track addresses in the directory. 
The data set can be considered as one continuous set of tracks 
regardless of how the space was actually allocated. 

If there is not sufficient space available in the directory for 
an additional entry, or not enough space available within the 
data set for an additional member, no new members can be stored. 
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PARTITIONED DATA SET DIRECTORY 

The directory of a partitioned data set occupies the beginning 
of the area allocated to the data set on a direct-access volume. 
It is searched and maintained by the FIND and STOW macro 
instructions. The directory consists of member entries arranged 
in ascending order according to the binary value of the member 
name or alias. 

Member entries vary in length and are blocked into 256-byte 
blocks. Each block contains as many complete entries as will fit 
in a maximum of 254 bytes; any remaining bytes are left unused 
and are ignored. Each directory block contains a 2-byte count 
field that specifies the number of active bytes in a block 
(including the count field). As shown in Figure 43, each block 
is preceded by a hardware-defined key field containing the name 
of the last member entry in the block, that is, the member name 
with the highest binary value. 


Count 



Bytes 


Key 

Data 

Name of 
Last 

Entry in 
Block 


Number of 
Bytes Used 
(Maximum 
256) 

Member 

Entry A 

Member 
Entry B 

V. _ _/ 

v- y v 


Member 
Entry N 


SUnused: 


254 


Figure 43. 


A Partitioned Data Set Directory Block 


Each member entry contains a member name or alias. Each entry 
also contains the relative track address of the member and a 
count field, as shown in Figure 44. In addition, it may contain 
a user data field. The last entry in the last directory block 
has a name field of maximum binary value—all Is. 
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Figure 44. A Partitioned Data Set Directory Entry 


NAME 

specifies the member name or alias. It contains up to 8 
alphameric characters, left-justified and padded with 
blanks if necessary. 


TTR 

is a pointer to the first block of the member; TT is the 
number of the track, relative to the beginning of the data 
set, and R is the number of the block, relative to the 
beginning of that track. 

Note: This pointer is created by adding 1 to the TTR for 
the last block of the previous member (which is an 
end-of-file mark). If track TT is full, the next block will 
begin at record 1 of track TT + 1, and the pointer will be 
updated accordingly. The control program finds the block by 
searching in multitrack mode using TT(R-l) as a search 
argument. 


specifies the number of halfwords contained in the user 
data field. It may also contain additional information 
about the user data field, as shown below: 


Bits 0 1-2 3-7 


0 when set to 1, indicates that the NAME field contains 
an alias. 

1-2 specifies the number of pointers to locations within 
the member. 

A maximum of three pointers is allowed in the user 
data field. Additional pointers may be contained in a 
record referred to as a note list, discussed below. 
The pointers can be updated automatically if the data 
set is moved or copied by a utility program such as 
IEHMOVE. The data set must be marked unmovable under 
the following conditions 1 
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• More than three pointers are used in the user data 
field. 

• The pointers in the user data field or note list 
do not conform to the standard format. 

• The pointers are not placed first in the user data 
field. 

• Any direct access address (absolute or relative) 
is embedded in any data blocks or in another data 
set that refers to this data set. 

3-7 contains a binary value indicating the number of 

halfwords of user data. This number must include the 
space used by pointers in the user data field. 

You can use the user data field to provide variable data as 
input to the STOW macro instruction. If pointers to locations 
within the member are provided, they must be 4 bytes long and 
placed first in the user data field. The user data field format 
is as follows*’ 


User Data 


TTRN 

TTRN 

TTRN 

Optional 


TT is the relative track address of the note list or area to 
which you are pointing. 

R is the relative block number on that track. 

N is a binary value that indicates the number of additional 
pointers contained in a note list pointed to by the TTR. If 
the pointer is not to a note list, N = 0. 

A note list consists of additional pointers to blocks within the 
same member of a partitioned data set. You can divide a member 
into subgroups and store a pointer to the beginning of each 
subgroup in the note list. The member may be a load module 
containing many control sections (CSECTs), each CSECT being a 
subgroup pointed to by an entry in the note list. You get the 
pointer to the beginning of the subgroup by using the NOTE macro 
instruction after you write the first record of the subgroup. 
Remember that the pointer to the first record of the member is 
stored in the directory entry by the system. 

If the existence of a note list was indicated as shown above, 
the list can be updated automatically when the data set is moved 
or copied by a utility program such as IEHMOVE. Each 4-byte 
entry in the note list has the following format? 


TTRX 


TT is the relative track address of the area to which you are 
pointing. 

R is the relative block number on that track. 

X is available for any use. 

To place the note list in the partitioned data set, you must use 
the WRITE macro instruction. After checking the write operation, 
use the NOTE macro instruction to determine the address of the 
list and place that address in the user data field of the 
directory entry. 
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PROCESSING A MEMBER OF A PARTITIONED DATA SET 


Because a member of a partitioned data set is sequentially 
organised* it is processed in the same manner as a sequential 
data set. Either the basic or queued access technique can be 
used. However, you cannot alter the directory when using the 
queued technique. 

To locate a member or to process the directory, several macro 
instructions are provided by the operating system. The BLDL 
macro instruction can be used to structure a list of directory 
entries in virtual storage; the FIND macro instruction locates a 
member of the data set for subsequent processing; the STOW macro 
instruction adds, deletes, replaces, or changes a member name in 
the directory. To use these macro instructions, you must specify 
DSORG^PO or POU in the DCB macro instruction. Before issuing 
FIND, BLDL, or STOW macro instruction, you must check all 
preceding input/output operations for completion. 


BLDL—Construct a Directory Entry List 

The BLDL macro instruction is used to place directory 
information in virtual storage. The data is placed in a build 
list, which you construct before the BLDL macro instruction is 
issued. The format of the list is similar to that of the 
directory. For each member name in the list, the system supplies 
the address of the member and any additional information 
contained in the directory entry. Note that if there is more 
than one member name in the list, the member names must be in 
collating sequence regardless of whether the members are from 
the same library or from different libraries. 

You can optimize retrieval time by directing a subsequent FIND 
macro instruction to the build list rather than the directory to 
locate the member to be processed. 

The build list, as shown in Figure 45, must be preceded by a 
4-byte list description that indicates the number of entries in 
the list and the length of each entry (12 to 76 bytes). The 
first 8 bytes of each entry contain the member name or alias. 

The next 6 plus some control data. If there is no user data 
entry, only the TTR and C fields are required. If additional 
information is to be supplied from the directory, up to 62 bytes 
can be reserved. 


FIND—Position to a Member 

To determine the starting address of a specific member, you must 
issue a FIND macro instruction. The system places the correct 
address in the data control block so that a subsequent input or 
output operation begins processing at that point. 

There are two ways you can direct the system to the right member 
when you use the FIND macro instruction: specify the address of 
an area containing the name of the member or specify the address 
of the TTR field of the entry in a build list you have created 
by using the BLDL macro instruction. In the first case, the 
system searches the directory of the data set for the relative 
track address; in the second case, no search is required because 
the relative track address is in* the build list entry. 
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(Each entry starts on halfword boundary) 


List 

Description 


, Filled in by BLDL 

ffll ,-— N 

Member 

Name (C) 

TTR 

(3) 

K 

(1) 

Z 

(1) 

c 

(1) 

- 7 /- 

User Data 
(C Halfwords) 

_______ J I _ 






\ 







1 







] 

1 

- -- 

—-- 

_ 



- 



Programmer Supplies: 

FF Number of member entries in list. 

LL Even number giving byte length of each entry (minimum of 12). 
Member name Eight bytes, left-justified. 

BLDL Supplies: 

TTR Member starting location. 

K If only data set = 0. If concatenation = number. 

Not required if no user data. 

Z Source of directory entry. Private library = 0. 

Link library = 1. Job or step library = 2. 

Not required if no user data. 

C Same C field from directory. Gives number of user data halfwords. 
User data As much as will fit in entry. 


Figure 45. Build List Format 


The system will also search a concatenated series of directories 
when.(l) a DCB is supplied that is opened for a concatenated 
partitioned data set of (2) a DCB is not supplied, in which case 
either JOBLIB or 5TEPLIB (themselves perhaps concatenated) 
followed by LINKLIB is searched. 

If you want to process only one member, you can process it as a 
sequential data set (DS0RG=PS) using either BSAM or Q5AM. You 
indicate the name of the member you want to process and the name 
of the partitioned data set in the DSNAME parameter of the DD 
statement. When you open the data set, the system places the 
starting address in the data control block so that a subsequent 
GET or READ macro instruction begins processing at that point. 
You cannot use the FIND, BLDL, or STOW macro instructions when 
you are processing one member as a sequential data set. 

Since the DCBRELAD address in the data control block is updated 
when the FIND macro is used, you should not issue the FIND macro 
after WRITE and STOW processing without first closing the data 
set and reopening it for INPUT processing. 


STOW—Update the Directory 

When you add several members to a partitioned data set, you must 
issue a STOW macro instruction after writing each member so that 
an entry for each one will be added to the directory. To use the 
STOW macro instruction, DSORG=PO or POU must be specified in the 
DCB macro instruction. 
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You can also use the STOW macro instruction to delete, replace, 
or change a member name in the directory, as well as to store 
additional information with the directory entry. Since an alias 
can also be stored in the directory the same way, you should be 
consistent in altering all names associated with a given member. 
For example, if you replace a member, you must delete related 
alias entries or change them so that they point to the new 
member. 

If you add only one member to a partitioned data set and 
indicate the member name in the DSNAME parameter of the DD 
statement, it is not necessary for you to use BPAM and a STOW 
macro instruction in your program. If you wish to do so, you may 
use BPAM and STOW, or BSAM or QSAM. If you use a sequential 
access method, or if you use BPAM and issue a CLOSE macro 
instruction without issuing a STOW macro instruction, the system 
will issue a STOW macro instruction using the member name you 
have specified on the DD statement. When the system issues the 
STOW, the directory entry that is added is the minimum length 
(12 bytes). This automatic STOW macro instruction will not be 
issued if the CLOSE macro instruction is a TYPE=T or if the TCB 
indicates the task is being abnormally terminated when the DCB 
is being closed. The DISP parameter on the DD statement 
determines what directory action parameter will be chosen by the 
system for the STOW macro instruction. 

If DISP=NEW or MOD was specified, a STOW macro instruction with 
the add option will be issued. If the member name on the DD 
statement is not present in the data set directory, it will be 
added. If the member name is already present in the directory, 
the task will be abnormally terminated. 

If DISP=OLD was specified, a STOW macro instruction with the 
replace option will be issued. The member name will be inserted 
into the directory, either as an addition if the name is not 
already present or as a replacement if the name is present. 

Thus, with an existing data set, you should use DISP=0LD to 
force a member into the data set; you should use DISP=M0D to add 
members with protection against the accidental -destruction of an 
existing member. 


CREATING A PARTITIONED DATA SET 

If you have no need to add entries to the directory, that is, 
the STOW and BLDL macro instructions will not be used, you can 
create a new data set and write the first member as follows (see 
Figure 46 on page 99)= 

• Code DS0RG=PS or DS0RG=PSU in the DCB macro instruction. 

• Indicate in the DD statement that the data is to be stored 
as a member of a new partitioned data set, that is, 
DSNAME=name (membername) and DISP = NEW. 

• Request space for the member and the directory in the DD 
statement. 

• Process the member with an OPEN macro instruction, a series 
of PUT or WRITE macro instructions, and then a CLOSE macro 
instruction. A STOW macro instruction is issued 
automatically when the data set is closed. 

As a result of these steps, the data set and its directory are 
created, the records of the member are written, and a 12-byte 
entry is made in the directory. 

To add additional members to the data set, follow the same 
procedure. However, a separate DD statement (with the space 
request omitted) is required for each member. The disposition 
should be specified as modify, DISP=M0D. The data set must be 
closed and reopened each time new member is specified. 
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To take full advantage of the STOW macro instruction, and thus 
the BLDL and FIND macro instructions in future processing, you 
can provide additional information with each directory entry. 
You do this by using the basic access technique, which also 
allows you to process more than one member without closing and 
reopening the data set, as follows (see Figure 47). 

• Request space in the DD statement for the members and the 
directory. 

• Define DS0RG=P0 or DS0RG=P0U in the DCB macro instruction. 

• Use WRITE and CHECK to write and check the member records. 

• Use NOTE to note the location of any note list written 
within the member, if there is a note list. 


//PDSDD DD —,DSNAME=MASTFILE(MEMBERK),SPACE=(TRK,(100,5,7)), C 

DISP=(NEW,KEEP) 


OUTDCB DCB 


- -, DS0RG = PS,DDNAME=PDSDD,- 


OPEN (OUTDCB,(OUTPUT)) 

PUTCor WRITE] 


CLOSE (OUTDCB) 


Automatic Stow 


Figure 46. Creating One Member of a Partitioned Data Set 


//PDSDD 

DD 

OUTDCB 

DCB 

OPEN 

XX 

WRITE 

CHECK 

X 

WRITE 

CHECK 

X 

NOTE 

ST 

X 


X 

WRITE 

CHECK 

NOTE 

ST 

STOW 


DSNAME=MASTFILE,SPACE=(TRK,(100,5,7)),DISP=M0D 

--,DS0RG=P0,DDNAME=PDSDD,-- 
(OUTDCB,(OUTPUT)) 

Write and check first record of member. 
The system will supply the relative 
track address for the directory entry. 
Write and check remaining records of 
member. 


If you are dividing 
subgroups, note the 
record in subgroup, 
in note list. 

Write note list at end 


the member into 
location of the first 
storing pointer 


of member. 

storing 
for 


Note location of note list, 
pointer in list for STOW. 

Enter information in directory 
x this member after all records and note 

x lists are written. 

Repeat from xx for each additional member 

CLOSE (OUTDCB) 


Figure 47. Creating Members of a Partitioned Data Set Using STOW 


When all the member records have been written, issue a STOW 
macro instruction to enter the member name, its location 
pointer, and any additional data in the directory. 


Continue to write, check, note, and stow until all the 
members of the data set and the directory entries have been 
written. 
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RETRIEVING 


//PDSDD 

INDCB 


Figure 48. 


A MEMBER OF A PARTITIONED DATA SET 

r 

To retrieve a specific member from a partitioned data set, 
either the basic or queued access technique can be used as 
follows (see Figure 48) ; 

• Code DS0RG=PS or DS0RG = PSIJ in the DOB macro instruction. 

• Indicate in the DD statement that the data is a member of an 
existing partitioned data set by coding 
DSNAME = name(membername) and DISP=0LD. 

• Process the member with an OPEN macro instruction, a series 
of GET and READ macro instructions, and then a CLOSE macro 
instruction. 


DD —,DSNAME=MASTFILE(MEMBERK),DISP=0LD 

DCB ~,DSORG = PS,DDNAME = PDSDD,~ 

OPEN (INDCB) Automatic Find 

GET (or READ) 

CLOSE (INDCB) 


Retrieving One Member of a Partitioned Data Set 


When your program is executed, the directory is searched 
automatically and the location of the member is placed in the 
DCB. 

To process several members without closing and reopening, or to 
take advantage of additional data in the directory, this 
technique should be used (see Figure 49)5 

• Code DS0RG=P0 or POU in the DCB macro instruction. 

• Build a list (BLDL) of needed member entries from the 
directory. 

• Indicate in the DD statement the data set name of the 
partitioned data set by coding DSNAME=name and DISP=QLD. 

• Use the FIND or POINT macro instruction to prepare for 
reading the member records. 

• The records may be read from the beginning of the member, or 
a note list may be read first, to obtain additional 
locations that point to subcategories within the member. 

• Read (and check) the records until all those required have 
been processed. 

• Point to additional categories, if required, and read the 
records. 

• Repeat this procedure for each member to be retrieved. 
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//PDSDD 


DD 


DSNAME=MASTFILE,DISP=OLD 


INDCB 


**Read 


Repeat 


DCB 

OPEN 

BLDL 

FIND (or 
note list. 
READ 
CHECK 
POINT 
READ 
CHECK 

from ** for 

CLOSE 


,DS0RG=P0,DDNAME=PDSDD» — 

(INDCB) 

Build a list of selected member names 
in virtual storage. 

POINT) 


Locate subgroup by using note list. 


Read member records, 
each additional member. 

(INDCB) 


Figure 49. Retrieving Several Members of a Partitioned Data Set Using BLDL, 
FIND, and POINT 


UPDATING A MEMBER OF A PARTITIONED DATA SET 

A member of a partitioned data set can be updated in place, or 
can be deleted and rewritten as a new member. 


Updating in Place 

When you update in place, you read records, process them, and 
write them back to their original positions without destroying 
the remaining records on the track. The following rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro 
instruction. To perform the update, you can use only the 
READ, WRITE, CHECK, NOTE, POINT, FIND, and BLDL macro 

instructions. 

• You cannot update concatenated partitioned data sets. 

• You cannot use chained scheduling. 

• You cannot delete any record or change its length; you 
cannot add new records. 

A record must be retrieved by a READ macro instruction before it 
can be updated by a WRITE macro instruction. Both macro 
instructions must be execute forms that refer to the same DECB; 
the DECB must be provided by a list form. (The execute and list 
forms of the READ and WRITE macro instructions are described in 
QS/VS2 MVS Data Management Macro Instructions .) 


UPDATING WITH QSAM : You can update a member of a partitioned 
data set using the locate mode of QSAM (DCB specifies MACRF=PL) 
and using the PUTX macro instruction. The DD statement must 
specify the data set and member name in the DSNAME parameter. 
This method allows only the updating of the member specified in 
the DD statement. 

UPDATING WITH OVERLAPPED OPERATIONS: To overlap input/output and 
CPU activity, you can start several read or write operations 
before checking the first for completion. You cannot overlap 
read and write operations, however, as operations of one type 
must be checked for completion before operations of the other 
type are started or resumed. Note that each concurrent read or 
write operation requires a separate channel program and a 
separate DECB. If a single DECB were used for successive read 
operations, only the last record read could be updated. 
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In Figure 50, overlap is achieved by having a read or write 
request outstanding while each record is being processed. Note 
the use of the execute and list forms of the READ-and WRITE 
macro instructions, identified by the operands MF = E and MF=L. 


//PDSDD 

DD 

DSNAME=MASTFILE(MEMBERK),DISP= 

OLD,— 

UPDATDCB 

DCB 

DSORG=PS,DDNAME=PDSDD,MACRF=(R 

,W),NCP=2,E0DAD=FINISH 


READ 

DECBA,SF,UPDATDCB,AREAA,MF=L 

Define DECBA 


READ 

DECBB,SF,UPDATDCB,AREAB,MF=L 

Define DECBB 

AREAA 

DS 

— 

Define buffers 

AREAB 

DS 

— 



OPEN 

(UPDATDCB,UPDAT) 

Open for update 


LA 

2,DECBA 

Load DECB addresses 


LA 

3,DECBB 


READRECD 

READ 

(2),SF,MF=E 

Read a record 

NEXTRECD 

READ 

(3),SF,MF=E 

Read the next record 


CHECK 

(2) 

Check previous read operation 

(If 

update 

is required* branch to R2UPDATE) 



LR 

4,3 

If no update is required. 


LR 

3,2 

switch DECB addresses in 


LR 

2,4 

registers 2 and 3 


B 

NEXTRECD 

and loop 


In the following statements* "R2" and "R3" refer to the records 

that were read using the DECBs whose addresses are in registers 2 and 3, 

respectively. Either register may point to either DECBA or DECBB. 


R2UPDATE CALL 
CHECK 
WRITE 

(If R3 requ 

CHECK 

B 

R3UPDATE CALL 
WRITE 
CHECK 
CHECK 
B 

FINISH CLOSE 


UPDATE,((2)) 
(3) 

(2) ,SF»MF=E 
res an update* 

(2) 

READRECD 
UPDATE,((3)) 
C3),SF,MF=E 
(2) 

(3) 

READRECD 
(UPDATDCB) 


Call routine to update R2 
Check read for next record 
(R3) Write updated R2 

branch to R3UPDATE) 

If R3 requires no update, 

check write for R2 and loop 

Call routine to update R3 

Write updated R3 

Check write for R2 

Check write for R3 

Loop 

End-of-Data exit routine 


Figure 50. Updating a Member of a Partitioned Data Set 


Rewriting a Member 

There is no actual update option that can be used to add or 
extend records in a partitioned data set. If you want to extend 
or add a record within a member, you must rewrite the complete 
member in another area of the data set. Since space is allocated 
when the data set is created, there is no need to request 
additional space. Note, however, that a partitioned data set 
must be contained on one volume. If sufficient space has not 
been allocated, the data set must be reorganized by the IEBC0PY 
utility program. 

When you rewrite the member, you must provide two DCBs, one for 
input and one for output. Both DCB macro instructions can refer 
to the same data set, that is, only one DD statement is 
required. 

You can reflect the change in location of the member either 
automatically, by indicating a disposition of OLD, or by using 
the STOW macro instruction. Although the old member is, in 
effect, deleted, its space cannot be reused until the data set 
is reorganized. 

If an out-of-space condition occurs when updating a PDS member, 
the error recovery procedure will STOW the PDS member as 
’TEMPNAME’. The original member will remain intact. 
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PROCESSING A PARTITIONED DATA SET RESIDING ON MSS 


If 0PTCD=H is specified in the DCB subparameter of a DD 
statement, it specifies that, if a Partitioned Data set is being 
opened for input and resides on an MSS device, then at OPEN time 
the data set is staged to EOF on the virtual DASD device. If the 
option is not specified, only the directory is staged at OPEN 
time and cylinder faults occur during processing. This option 
might be used with the IEBCOPY utility program opening the PDS 
to reorganize and compress the data space. This BPAM option, 
0PTCD=H, may only be coded on the DD statement. 


PROCESSING AN INDEXED SEQUENTIAL DATA SET 


The organization of an indexed sequential data set allows you a 
great deal of flexibility in the operations you can perform. The 
data set can be read or written sequentially, individual records 
can be processed in any order, records can be deleted, and new 
records can be added. The system automatically locates the 
proper position in the data set for new records and makes any 
necessary adjustments when records are deleted. 

The queued access technique must be used to create an indexed 
sequential data set. It can also be used to sequentially process 
or update the data set and to add records to the end of the data 
set. The basic access technique can be used to insert new 
records between records already in the data set and to update 
the data set directly. 


INDEXED SEQUENTIAL DATA SET ORGANIZATION 

The records in an indexed sequential data set are arranged 
according to collating sequence by a key field in each record. 
Each block of records is preceded by a key field that 
corresponds to the key of the last record in the block. 

An indexed sequential data set resides on direct-access storage 
devices and can occupy up to three different areas: 

• Prime Area —This area, also called the prime data area, 
contains data records and related track indexes. It exists 
for all indexed sequential data sets. 

• Overflow Area —This area contains records that overflow from 
the prime area when new data records are added. It is 

optiona1. 

• Index Area —This area contains master and cylinder indexes 
associated with the data set. It exists for a data set that 
has a prime area occupying more than one cylinder. 

The indexes of an indexed sequential data set are analogous 
to the card catalog in a library. For example, if the 
library user knows the name of the book or the author, he 
can look in the card catalog and obtain a catalog number 
that will enable him to locate the book in the book files. 

He would then go to the shelves and proceed through rows 
until he found the shelf containing the book. Usually each 
row contains a sign to indicate the beginning and ending 
numbers of all books in that particular row. Thus, as he 
proceeded through the rows, he would compare the catalog 
number obtained from the index with the numbers posted on 
each row. Upon locating the proper row, he would then search 
that row for the shelf that contained the book. Then he 
would look at the individual book numbers on that shelf 
until he found the particular book. 

ISAM uses the indexes in much the same way to locate records 
in an indexed sequential data set. 
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As the records are written in the prime area of the data 

set, the system accounts for the records contained on each / 

track in a track index area . Each entry in the track index ( 

identifies the key of the last record on each track. There V 

is a track index for each cylinder in the data set. If more 

than one cylinder is used, the system develops a 

highei—level index called a cylinder index . Each entry in 

the cylinder index identifies the key of the last record in 

the cylinder. To increase the speed of searching the 

cylinder index, you can request that a master index be 

developed for a specified number of cylinders, as shown in 

Figure 51. 

Rather than reorganize the whole data set when records are 
added, you can request that space be allocated for 
additional records in an overflow area. 


Prime Area 

Records are written in the prime area when the data set is 
created or updated. The last track of prime data is reserved for 
an end-of-file mark. The portion of Figure 51 labeled Cylinder 1 
illustrates the initial structure of the prime area. Although 
the prime area can extend across several noncontiguous areas of 
the volume, all the records are written in key sequence. Each 
record must contain a key; the system automatically writes the 
key of the highest record before each block. 


Master Index 



Figure 51. Indexed Sequential Data Set Organization 
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When the AB5TR option of the SPACE parameter of the DD statement 
is used to generate a multi volume prime area, the VTOC of the 
second volume and on all succeeding volumes must be contained 
within cylinder 0 of the volume. 



Index Areas 

The operating system generates track and cylinder indexes 
automatically. Up to three levels of master indexes are created 
if requested. 

TRACK INDEX : This is the lowest level of index and is always 
present. There is one track index for each cylinder in the prime 
area; it is written on the first trackCs) of the cylinder that 
it indexes. 

The index consists of a series of paired entries, that is, of a 
normal entry and an overflow entry for each prime track. For 
fixed-length records, each normal entry (and also DCBFIRSH) 
points to either record 0 or the first prime record on a shared 
track. For variable-length records, the normal entry contains 
the key of the highest record on the track and the address of 

the last record on the track. The overflow entry is originally 

the same as the normal entry. (This is why 100 appears twice on 

the track index for cylinder 1 in Figure 51 on page 104). The 
overflow entry is changed when records are added to the data 
set. Then the overflow entry contains the key of the highest 
overflow record and the address of the lowest overflow record 
logically associated with the track. Figure 52 on page 106 shows 
the format of a track index. 

If all the tracks allocated for the prime data area are not 
used, the index entries for the unused ones are flagged as 
inactive. The last entry of each track index is a dummy entry 
indicating the end of the index. When fixed-length record format 
has been specified, the remainder of the last track of each 
cylinder used for a track index contains prime data records if 
there is room for them. 

Each index entry has the same format. It is an unblocked, 
fixed-length record consisting of a count, a key, and a data 
area. The length of the key corresponds to the length of the key 
area in the record to which it points. The data area is always 
10 bytes long. It contains the full address of the track or 
record to which the index points, as well as the level of the 
index and the entry type. 

CYLINDER INDEX: For every track index created, the system 
generates a cylinder index entry. There is one cylinder index 
for a data set, each entry of which points to a track index. 
Since there is one track index per cylinder, there is one 
cylinder index entry for each cylinder in the prime data area, 
except in the case of a 1-cylinder prime area. As with track 
indexes, inactive entries are created for any unused cylinders 
in the prime data area. 

MASTER INDEX: As an optional feature, the operating system 
creates, at your request, a master index. The presence of this 
index makes long, serial searches through a large, cylinder 
index unnecessary. 
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Normal/Overflow Normal/Overflow 

Pair Pair 

f -*-V- - -\ 


Normal Overflow Normal Overflow 

Entry Entry Entry Entry 






S N 

Key 1 

Data^ 

Key 3 

Data^ 

Key 1 

Data^ 

Key 3 

Data* 1 

i 


1 

Normal key = key of the highest record on the prime data track 

^Normal data = address of the prime data track 

^Overflow key = key of the highest overflow record logically associated with the prime data track 
^Overflow data = address of the lowest overflow record logically associated with the prime data track 
Notes: 

• If there are no overflow records, overflow key and data entries are the same as normal key and data entries. 

• This figure is a logical representation only; that is, it makes no attempt to show the physical size of track index entries. 


Figure 52. Format of Track Index Entries 


You can specify the conditions under which you want a master 
index created. For example, if you have specified NTM=3 and 
0PTCD=M in your DCB macro instruction, a master index is created 
when the cylinder index exceeds,3 tracks. The master index 
consists of one entry for each track of cylinder index. If your 
data set is extremely large, a highet—level master index is 
created when the first-level master index exceeds three tracks. 
This highei—level master index consists of one entry for each 
track of the first-level master index. This procedure can be 
repeated for as many as three levels of master index. 


Overflow Areas 


As records are added to an indexed sequential data set, space is 
required to contain those records that will not fit on the prime 
data track on which they belong. You can request that a number 
of tracks be set aside as a cylinder overflow area to contain 
overflows from prime tracks in each cylinder. An advantage of 
using cylinder overflow areas is a reduction of search time 
required to locate overflow records. A disadvantage is that 
there will be unused space if the additions are unevenly 
distributed throughout the data set. 

Instead of, or in addition to, cylinder overflow areas, you can 
request an independent overflow area . Overflow from anywhere in 
the prime data area is placed in a specified number of cylinders 
reserved solely for overflow records. An advantage of having an 
independent overflow area is a reduction in unused space 
reserved for overflow. A disadvantage is the increased search 
time required to locate overflow records in an independent area. 

If you request both cylinder overflow and independent overflow, 
the cylinder overflow area is used first. It is a good practice 
to request cylinder overflow areas large enough to contain a 
reasonable number of additional records and an independent 
overflow area to be used as the cylinder overflow areas are 
filled. 
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ADDING RECORDS TO AN INDEXED SEQUENTIAL DATA SET 


Either the queued access technique or the basic access technique 
may be used to add records to an indexed sequential data set. A 
record to be inserted between records already in the data set 
must be inserted by the basic access method using WRITE KN (key 
new). Records added to the end of a data set, that is, records 
with successively higher keys, may be added to the prime data 
area or the overflow area by the basic access method using WRITE 
KN, or they may be added to the prime data area by the queued 
access technique using the PUT macro instruction. 


Inserting New Records into an Existing Indexed Sequential Data Set 

As you add records to an indexed sequential data set, the system 
inserts each record in its proper sequence according to the 
record key. The remaining records on the track are then moved up 
one position each. If the last record does not fit on the track, 
it is written \n the first available location in the overflow 
area. A 10-byte link field is added to the record put in the 
overflow area to connect it logically to the correct track. The 
proper adjustments are made to the track index entries. This 
This procedure is illustrated in Figure 53 on page 108. 

Subsequent additions are written either on the prime track or as 
part of the overflow chain from that track. If the addition 
belongs after the last prime record on a track but before a 
previous overflow record from that track, it is written in the 
first available location in the overflow area. Its link field 
contains the address of the next record in the chain. 


Adding New Records to the End of an Indexed Sequential Data Set 

Records added to the end of a data set, that is, records with 
successively higher keys, may be added by the basic access 
method using WRITE KN (key new), or by the queued access method 
using the PUT macro instruction (resume load). In either case 
records may be added to the prime data area. 

When you use the WRITE KN macro instruction, the record being 
added is placed in the prime data area only if there is room for 
it on the prime data track containing the record with the 
highest key currently in the data set. If there is not 
sufficient room on that track, the record is placed in the 
overflow area and linked to that prime track even though 
additional prime data tracks originally allocated have not been 
filled. 

When you use the PUT macro instruction (resume load), records 
are added to the prime data area until the space originally 
allocated is filled. Once this allocated prime area is filled, 
you can add records to the data set using WRITE KN, in which 
case they will be placed in the overflow area. Resume load is 
discussed in more detail later under "Creating an Indexed 
Sequential Data Set." 
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Figure 53. Adding Records to an Indexed Sequential Data Set 


In order to add records with successively higher keys using the 

PUT macro instruction (resume load) 5 

• The key of any record to be added must be higher than the 

highest key currently in the data set. 

• The DD statement must specify DISP=M0D or the EXTEND option 

is specified in the OPEN macro. 

• The data set must have been successfully closed when it was 
created or when records were previously added using the PUT 
macro instruction. 


108 0S/VS2 Data Management Services Guide 














You may continue to add fixed-length records in this manner 
until the original space allocated for prime data is exhausted. 

When you add records to an indexed sequential data set using the 
PUT macro instruction (resume load), new entries are also made 
in the indexes. During resume load on a data set with a 
partially filled track and/or a partially filled cylinder, the 
track index entry and/or the cylinder index entry is overlaid 
when the track or cylinder is filled. If resume load abnormally 
terminates after these index entries have been overlaid, a 
subsequent resume load will get a sequence check when adding a 
key that is higher than the highest key at the last successful 
CLOSE but lower than the key in the overlaid index entry. When 
the SYNAD exit is taken for a sequence check, register 0 
contains the address of the highest key of the data set. 


MAINTAINING AN INDEXED SEQUENTIAL DATA SET 

An indexed sequential data set must be reorganized occasionally 
for two reasons; 

• The overflow area will eventually be filled. 

• Additions increase the time required to locate records 
directly. 

The frequency of reorganization depends on the activity of the 
data set and on your timing and storage requirements. There are 
two ways you can accomplish reorganization: 

• You can reorganize the data set in two passes by writing it 
sequentially into another area of direct-access storage or 
magnetic tape and then recreating it in the original area. 

• You can reorganize the data set in one pass by writing it 
directly directly into another area of direct-access 
storage. In this case, the area occupied by the original 
data set cannot be used by the reorganized data set. 

The operating system maintains statistics that are pertinent to 
reorganization. The statistics, written on the direct-access 
volume and available in the DCB for checking, include the number 
of cylinder overflow areas, the number of unused tracks in the 
independent overflow area, and the number of references to 
overflow records other than the first. They appear in the R0RG1, 
R0RG2, and R0RG3 fields of the DCB. 

If you indicate when creating or updating the data set that you 
want to be able to flag records for deletion during updating, 
you can set the delete code (the first byte of a fixed-length 
record or the fifth byte of a variable-length record) to X'FF f . 
If a flagged record is forced off its prime track during a 
subsequent update, it will not be rewritten in the overflow 
area, as shown in Figure 54 on page 110 unless it has the 
highest key on that cylinder. Similarly, when you process 
sequentially, flagged records are not retrieved for processing. 
During direct processing, flagged records are retrieved like any 
other records, and you should check them for the delete code. 

Note that a WRITE KN (key new) to a data set containing 
variable-length records removes all of the deleted records from 
that prime data track. 

Note that to use the delete option, RKP must be greater than 0 
for fixed-length records and greater than 4 for variable-length 
records. 
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Delete Code 



Record 100 is 
marked for deletion 
and record 25 is 
added to the 
data set 





Figure 54. Deleting Records From an Indexed Sequential Data Set 


► 
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INDEXED SEQUENTIAL BUFFER AND WORK AREA REQUIREMENTS 


The qnly cease in which you will ever have to compute the buffer 
length (BUFL) requirements for your program is when you use the 
BUILD or GETPOOL macro instruction to construct the buffer area 
If you are creating an indexed sequential data set (using the 
PUT macro instruction ), each buffer must be 8 bytes longer than 
the blocksize to allow for the hardware count field/ that is: 


Buffer length = 8 + Blocksize 


(8) 

Data 


(BLK5IZE) 


<-Buffei-> 


One exception to this formula arises when you are dealing with 
an unblocked format-F record whose key field precedes the data 
field; its relative key position is 0 (RKP=0). In that case the 
key length must also be added/ that is : 


Buffer length = 8 + Key length + Record length 


(8) 

Key 

Data 


(KEYLEN) 

(LRECL) 


<-Buffer-> 


The buffer requirements for using the queued access technique to 
read or update (using the GET or PUTX macro instruction) an 
indexed sequential data set are discussed below. 

For fixed-length unblocked records when both the key and data 
are to be read and for variable-length unblocked records/ 
padding is added so that the data will be on a doubleword 
boundary/ that is*- 

Buffer length = Key length + Padding + 10 + Blocksize 


Key 


L i nk 

Data 

(KEYLEN) 

Padding 

(10) 

(BLKSIZE) 


<-Buffer-> 


For fixed-length unblocked records when only data is to be read : 


Buffer length = 16 + LRECL 


Padding 

Link 

Data 

(6) 

(10) 

(LRECL) 


<-Buffei-> 


For fixed-length blocked records: 


Buffer length = 16 + Blocksize 


Padding 

Link 

Data 

(6) 

(10) 

(BLKSIZE) 


<-Buffei-> 


For variable-length blocked records/ padding is 2 if the buffer 
starts on a fullword boundary that is not also a doubleword 
boundary or 6 if the buffer starts on a doubleword boundary/ 
that is: 


Buffer length = 12 or 16 + Blocksize 


Padding 

Link 

Data 


(10) 

(BLKSIZE) 


<-Buffei-> 
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If you are using the input data set with fixed-length, unblocked 
records as a basis for creating a new data set, a work area is 
required. 

The size of the work area is given by* 


Work area = Key length + Record length 


Key 


Data 
( LRECL) 


< 


Work Area 


> 


If you are reading only the data portion of fixed-length 
unblocked records or variable-length records, the work area is 
the same size as the record, that is: 


Work area = Record length 


Data 

(LRECL) 


<-Work Area-> 


When you use the basic access technique to update records in an 
indexed sequential data set, the key length field need not be 
considered in determining your buffer requirements. The area for 
fixed-length records must be: 


Buffer length = 16 + Blocksize 


Padding 

L i nk 

Data 

(6) 

(10) 

(BLKSIZE) 


<-Buffer-> 


For variable-length records, padding is 2 if the buffer starts 
on a fullword boundary that is not also a doubleword boundary or 
6 if a buffer starts on a doubleword boundary. Thus, the area 
must be: 


Buffer length = 12 or 16 + Blocksize 



Link 

Data 

Padding 

(10) 

(BLKSIZE) 


<-Buffei-> 


You can speed up the process of adding fixed-length or 
variable-length records to a data set by using the MSWA 
parameter of the DCB macro instruction to provide a special work 
area for the operating system. The size of the work area (SMSW 
parameter in the DCB) must be large enough to contain a full 
track of data, the count fields of each block, and the work 
space for inserting the new record. 

The size of the work area needed varies according to the record 
format and the device type. You can calculate it during 
execution using device-dependent information obtained with the 
DEVTYPE macro instruction and data set information from the DSCB 
obtained with the OBTAIN macro instruction. The DEVTYPE and 
OBTAIN macro instructions are discussed in 0S/VS2 System 
Programming Library: Data Management . 

Note that you can use the DEVTYPE macro instruction only if the 
index and prime areas are on devices of the same type or if the 
index area is on a device with a larger track capacity than that 
of the device containing the prime area. If you are not trying 
to maintain device independence, you may precalculate the size 
of the work area needed and specify it in the SMSW field of the 
DCB macro instruction. The maximum value for SMSW is 65,535. 
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For calculating the size of the work area, refer to the storage 
device capacities shown in Figure 62 on page 132 under 
"Estimating Space Requirements" and the device overhead formulas 
given in the same section. 

For fixed-length blocked records, SMSW is calculated as follows: 

SMSW = DS2HIRPR(BLKSIZE+8)+LRECL+KEYLEN 

The formula for fixed-length unblocked records is 

SMSW = DS2HIRPR(KEYLEN+LRECL+8)+2 

The value for DS2HIRPR is in the index (format-2) DSCB. 0S/VS2 
System Programming Library: Debugging Handkook shows the exact 
location of this field in the index DSCB. If you don’t use the 
MSWA and SMSW parameters, the control program supplies a work 
area using the formula BLKSIZE + LRECL + KEYLEN. 

For variable-length records, SMSW may be calculated by one of 
two methods. The first method njay lead to faster processing 
although it may require more storage than the second method. 

The first method is as follows: 

SMSW = DS2HIRPR(BLKSIZE+8) + L RECL+KEYLEN + 10 

The second method is as follows: 

SMSW = 

( Trk Cap-Bn+1 )(BLKSIZE)+8(DS2HIRPR)+LRECL+KEYLEN+10+(REM-N-KEYLEN) 
Bi 

In all of the above formulas, the terms BLKSIZE, LRECL, KEYLEN, 
and SMSW are the same as the parameters in the DCB macro 
instruction (Trk Cap=track capacity). REM is the remainder of 
the division operation in the formula and N is the first 
constant in the Bi formulas described in Figure 63 on page 133 
(REM-N-KEYLEN) is added only if it is positive. The second 
method yields a minimum value for SMSW. Therefore, the first 
method is valid only if its application results in a value 
higher than the value that would be derived from the second 
method. If neither MSWA nor SMSW is specified, the control 
program supplies the work area for variable-length records, 
using the second method to calculate the size. 

Another technique to increase the speed of processing is to 
provide space in virtual storage for the highest-level index. To 
specify the address of this area, use the MSHI operand of the 
DCB. When the address of this area is specified, you must also 
specify its size, which you can do by using the SMSI operand of 
the DCB. The maximum value for SMSI is 65,535. If you do not use 
this technique, the index on the volume must be searched. If the 
high-level index is greater than 65,535 bytes in length, your 
request for the high-level index in storage is ignored. 

The size of the storage area (SMSI parameter) varies. To 
allocate that space during execution, you can find the size of 
the high-level index in the DCBNCRHI field of the DCB during 
your DCB exit routine or after the data set is open. Use the 
DCBD macro instruction to gain access to the DCBNCRHI field (see 
"Modifying the Data Control Block" in Part 1). You can also find 
the size of the high-level index in the DS2N0BYT field of the 
index (format 2) DSCB, but you must use the utility program 
IEHLIST to print the information in the DSCB. You can calculate 
the size of the storage area required for the high-level index 
by using the formula 

SMSI = /Number of Tracks \ /Number of Entries\ /Key Length + 10 
\in High-Level Indexj yper Track / \ 

The formula for calculating the number of tracks in the 
high-level index is in the section "Calculating Space 
Requirements for an Indexed Sequential Data Set" in Part 3. When 
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a data set is shared and has the DCB integrity feature 
(DISP=SHR), the high-level index in storage is not updated when 
DCB fields are changed. 


CONTROLLING AN INDEXED SEQUENTIAL DATA SET DEVICE 

An indexed sequential data set is processed sequentially or 
directly. Direct processing is accomplished by the basic access 
technique. Because you provide the key for the record you want 
read or written, all device control is handled automatically by 
the system. If you are processing the data set sequentially, 
using the queued access technique, the device is automatically 
positioned at the beginning of the data set. 

In some cases, you may wish to process only a section or several 
separate sections of the data set. You do this by using the SETL 
macro instruction, which directs the system to begin sequential 
retrieval at the record having a specific key. The processing of 
succeeding records is the same as for normal sequential 
processing, except that you must recognize when the last desired 
record has been processed. At this point, issue the ESETL macro 
instruction to terminate sequential processing. You can then 
begin processing at another point in the data set. 


SETL—Specify Start of Sequential Retrieval 

The SETL macro instruction enables you to retrieve records 
starting at the beginning of an indexed sequential data set or 
at any point in the data set. Processing -that is to start at a 
point other than the beginning can be requested in the form of a 
record key, a key class (key prefix), or an actual address of a 
prime data record. 

The key class concept is useful because you do not have to know 
the whole key of the first record to be processed. A key class 
comprises all of the keys that begin with identical characters. 
The key class is defined by specifying the desired characters of 
the key class at the address specified in the lowei—limit 
operand of the SETL macro and setting the remaining characters 
to the right of the key class to binary zeros. 

To use actual addresses, you must keep an account of where the 
records were written when the data set was created. The device 
address of the block containing the record just processed by a 
PUT-move macro instruction is available in the 8-byte data 
control block field DCBLPDA. For blocked records the address is 
the same for each record in the block. 


Normally, when a data set is created with the delete option 
specified, deleted records cannot be retrieved using the QISAM 
retrieval mode. When the delete option is not specified in the 
DCB, the SETL macro options function as follows : 


SETL B Start at first record in the data set 

SETL K Start with record having the specified key 

SETL KH Start with record whose key is equal to or higher than 
the specified key 

SETL KC Start with first record having a key that falls into 
the specified key class 

SETL I Start with the record found at the specified 

direct-access address in the prime area of the data set 


Because the DCBOPTCD field in the DCB can be changed after the 
data set is created (by respecifying the OPTCD in the DCB or DD 
card), it is possible to retrieve deleted records. In this case, 
SETL functions as noted above. 


114 0S/VS2 Data Management Services Guide 







When the delete option is specified in the DCB, the SETL macro 
options function as follows : 


SETL B Start retrieval at first nondeleted record in the data 
set 

SETL K Start retrieval at record matching the specified key if 
that record is not deleted. If the record is deleted, 
an NRF (no record found) indication is set in the 
DCBEXCD field of the DCB, and SYNAD is given control 

SETL KH Start with first nondeleted record whose key is equal 
to or higher than the specified key 

SETL KC Start with first nondeleted record having a key that 
falls into the specified key class or follows the 
specified key class 

SETL I Start with first nondeleted record following the 
specified direct-access address 


With the delete option not specified, QISAM retrieves and 
handles records marked for deletion like nondeleted records. 


Note-' Regardless of the SETL or delete option specified, the NRF 
condition will be posted in the DCBEXCD field of the DCB, and 
SYNAD is given control if the key or key class? 

• Is higher than any key or key class in the data set 

• Does not have a matching key or key class in the data set 


ESETL—End Sequential Retrieval 

The ESETL macro instruction directs the system to stop 
retrieving records from an indexed sequential data set. A new 
scan limit can then be set, or processing terminated. An 
end-of-data-set indication automatically terminates retrieval. 
An ESETL macro instruction must be executed before another SETL 
macro instruction (described above) using the same DCB is 
executed. 

Note? An ESETL macro instruction should be executed before 
another SETL macro instruction if the previous SETL macro 
instruction completed with an error. 


CREATING AN INDEXED SEQUENTIAL DATA SET 

You can create an indexed sequential data set in one step or in 
several steps. You can create the data set either by writing all 
records in a single step or by writing one group of records in 
one step and writing additional groups of records in subsequent 
steps. Writing records in subsequent steps is resume loading . 
When using either one step or several steps, you must present 
the records for writing in ascending order by key. 

To create an indexed sequential data set by the one-step method, 
you should proceed as follows? 

• Code DS0RG=IS or DS0RG=ISU and MACRF=PM or MACRF=PL in the 
DCB macro instruction. 

• Specify in the DD statement the DCB attributes DSORG^IS or 
DSQRG=ISU, record length (LRECL), blocksize (BLKSIZE), 
record format (RECFM), key length (KEYLEN), relative key 
position (RKP), options required (OPTCD), cylinder overflow 
(CYLOFL), and the number of tracks for a master index (NTM). 
Specify space requirements with the SPACE parameter. To 
reuse previously allocated space, omit the SPACE parameter 
and code DISP=(0LD, KEEP). 
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Open the data set for output. 


• Use the PUT macro instruction to place all the records or 
blocks on the direct-access volume. 

• Close the data set. 

The records that compose a newly created data set must be 
presented for writing in ascending order by key. You can merge 
two or more input data sets. If you want a data set with no 
records (a null data set), you must write at least one record 
when you create the data set. You can subsequently delete this 
record to achieve the null data set. 

If the records are blocked, you should not write a record with a 
hexadecimal value of FF and a key of hexadecimal value FF, This 
value is used for padding. If it occurs as the last record of a 
block, the record cannot be retrieved. If the record is moved to 
the overflow area, it is lost. 

When creating an indexed sequential data set, a procedure called 
loading , you can improve performance by using the 
full-track-index-write option. You do this by specifying 0PTCD=U 
in the DCB. This causes the operating system to accumulate 
track-index entries in virtual storage. Note that the 
ful1-track-index-write option can be used only for fixed-length 
records. 

If you do not specify this option, the operating system writes 
each normal-overflow pair of entries for the track index after 
the associated prime data track has been written. If you specify 
this option, the operating system accumulates track-index 
entries in virtual storage until either there are enough entries 
to fill a track or end-of-data or end-of-cylinder is reached. 
Then the operating system writes these entries as a group, 
writing one group for each track of track index. This option 
requires allocation of more storage space (the space in which 
the track-index entries are gathered), but the number of I/O 
operations required to write the index can be significantly 
decreased. 

When you specify the full-track-index-write option, the track 
index entries are written as fixed-length unblocked records. If 
a large enough area of virtual storage is not available, the 
entries are written as they are created, that is, in 
normal-overflow pairs. 

Once an indexed sequential data set has been created, its 
characteristics cannot be changed. However, for added 
flexibility, the system allows you to retrieve records using 
either the queued access technique with simple buffering, or the 
basic access technique with dynamic buffering. 

TAPE-TO-DISK.—INDEXED SEQUENTIAL DATA SET: The example in 
Figure 55 on page 117 shows the creation of an indexed 
sequential data set from an input tape containing 60-character 
records. The key by which the data setis organized is in 
positions 20-29. The output records will be an exact image of 
the input, except that the records will be blocked. One track 
per cylinder is to be reserved for cylinder overflow. Master 
indexes are to be built when the cylinder index exceeds six 
tracks. Reorganization information about the status of the 
cylinder overflow areas is to be maintained by the system. The 
delete option will be used during any future updating. 
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//INDEXDD 

DD 

DSNAME=SLATE.DICT(PRIME),DCB=(BLKSIZE=240,CYLOFL=1, 

C 

// 


DS0RG=IS,0PTCD= 

MYLR,RECFM= 

FB,LRECL=60,NTM=6,RKP=19, 

C 



KEYLEN=10),UNIT 

=3330,SPACE 

=(CYL,25,,C0NTIG),- 


//INPUTDD 

DD 

— 




ISLOAD 

START 

0 





DCBD 

DS0RG=IS 




ISLOAD 

CSECT 

OPEN 

(IPDATA,,ISDATA 

,(OUTPUT)) 



NEXTREC 

GET 

IPDATA 


Locate mode 



LR 

0,1 


Address of record in register 


PUT 

ISDATA,(0) 


Move mode 



B 

NEXTREC 




CHECKERR 

L * * 

3, =A (ISDAT A ) 


Initialize base for errors 



USING 

IHADCB,3 





TM 

DCBEXCD1,X'04’ 





BO 

OPERR 


Uncorrectable error 



TM 

DCBEXCD1,X T 20 ' 





BO 

NOSPACE 


Space not found 



TM 

DCBEXCD2,X T 80 1 





BO 

SEQCHK 


Record out of sequence 


Rest of error checking 




Error routine 





End of job routine CEODAD FOR IPDATA) 



IPDATA 

DCB 

— 




ISDATA 

DCB 

DDNAME=INDEXDD, 

DS0RG=IS,MACRF=(PM),SYNAD=CHECKERR 



Figure 55. Creating an Indexed Sequential Data Set 


To create an indexed sequential data set in more than one step, 
create the first group of records using the one step method 
described above. This first section must contain at least one 
data record. The remaining records can then be added to the end 
of the data set in subsequent steps using resume load. Each 
group to be added must contain records with successively higher 
keys. This method allows you to create the indexed sequential 
data set in several short time periods rather than in a single 
long one. 

This method also allows you to provide limited recovery from 
uncorrectable output errors. When an uncorrectable output error 
is detected, do not attempt to continue processing or to close 
the data set. If you have provided a SYNAD routine, it should 
issue the ABEND macro instruction to terminate processing. If no 
SYNAD routine is provided, the control program will terminate 
your processing. If the error shows that space in which to add 
the record was not found, you must close the data set; issuing 
subsequent PUT macro instructions can cause unpredictable 
results. You should begin recovery at the record following the 
end of the data as of the last successful close. The rerun time 
is limited to that necessary to add the new records, rather than 
to that necessary to recreate the whole data set. 

When you extend an indexed sequential data set with resume load, 
the disposition parameter of the DD statement must specify MOD. 
To ensure that the necessary control information is in the DSCB 
before attempting to add records, you should at least open and 
close the data set successfully on a version of the system that 
includes resume load. This need be done only if the data set was 
created on a previous version of the system. Records may be 
added to the data set by resume load until the space allocated 
for prime data in the first step has been filled. 

During resume load on a data set with a partially filled track 
and/or a partially filled cylinder, the track index entry and/or 
the cylinder index entry is overlaid when the track or cylinder 
is filled. Resume load for variable-length records begins at the 
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next sequential track of the prime data set. If resume load 
abnormally terminates after these index entries have been 
overlaid, a subsequent resume load will result in a sequence 
check when it adds a key that is higher than the highest at the 
last successful CLOSE but lower than the key in the overlaid 
index entry. When the SYNAD exit is taken for a sequence check, 
register 0 contains the address of the high key of the data set. 
However, if the SYNAD exit is taken during CLOSE, register 0 
will contain the IOB address. 


RETRIEVING AND UPDATING AN INDEXED SEQUENTIAL DATA SET 


Sequential Retrieval and Update 

To sequentially retrieve and update records in an indexed 
sequential data set* 

• Code DS0RG=IS or DS0RG=ISU to agree with what you specified 
when you created the data set, and MACRF=GL, MACRF=5K, or 
MACRF=PU in the DCB macro instruction. 

• Code a DD statement for retrieving the data set. The data 
set characteristics and options are as defined when the data 
set was created. 

• Open the data set. 

• Set the beginning of sequential retrieval (SETL). 

• Retrieve records and process as required, marking records 
for deletion as required. 

• Return records to the data set. 

• Use ESETL to end sequential retrieval as required and reset 
the starting point. 

• Close the data set to end all retrieval. 

SEQUENTIAL UPDATES—INDEXED SEQUENTIAL DATA SET: Assume that, 
using the data set created in the previous example, you are to 
retrieve all records beginning with 915. Those records with a 
date (positions 13-16) before today’s date are to be deleted. 

The date is in the standard form as returned by the system in 
response to the TIME macro instruction, that is, packed decimal 
OOyyddds. Overflow records can be logically deleted even though 
they cannot be physically deleted from the data set. 

One way to solve this problem is shown in Figure 56 on page 119. 
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//INDEXDD 

DD 

DSNAME=SLATE.DICT,- 


ISRETR 

START 

0 



DCBD 

DS0RG=IS 


ISRETR 

CSECT 




USING 

IHADCB,3 



LA 

3,ISDATA 



OPEN 

(ISDATA) 



SETL 

ISDATA,KC,KEYADDR 

Set scan limit 


TIME 


Today's date in regi: 


ST 

1,TODAY 


NEXTREC 

GET 

ISDATA 

Locate mode 


CLC 

19(10,1),LIMIT 



BNL 

ENDJOB 



CP 

12(4,1),TODAY 

Compare for old date 


BNL 

NEXTREC 



MVI 

0(1) ,X'FF’ 

Flag old record for 


PUTX 

ISDATA 

Return delete record 


B 

NEXTREC 


TODAY 

DS 

F 


KEYADDR 

DC 

C' 915' 

Key prefix 


DC 

XL 7’0 ’ 

Key padding 

LIMIT 

DC 

C'916' 



DC 

XL7’0 ’ 



CHECKERR 

Test DCBEXCD1 and DCBEXDE2 for error indication 
Error Routines 


ENDJOB 

ISDATA 


CLOSE (ISDATA) 

DCB DDNAME=INDEXDD,DSORG=IS,MACRF=(GL,SK,PU), 

SYHAD=CHECKRR 


Figure 56. Sequentially Updating an Indexed Sequential Data Set 


C 


Direct Retrieval and Update 

By using the basic indexed sequential access method (BISAM) to 
process an indexed sequential data set, you can make direct 
references to the records in the data set for the purpose of : 

• Direct retrieval of a record by its key 

• Direct update of a record 

• Direct insertion of new records 

Because the operations are direct, there can be no anticipatory 
buffering. However, the system provides dynamic buffering each 
time a read request is made, if specified. 

To ensure that the requested record is in virtual storage before 
you start processing, you must issue a WAIT or CHECK macro 
instruction. If you issue a WAIT macro instruction, you must 
test the exception code field of the DECB. If you issue a CHECK 
macro instruction, the system tests the exception code field in 
the DECB. If an error analysis routine has not been specified 
and a CHECK is issued, the program is abnormally terminated with 
a system completion code X'OOl'. In either case, if you wish to 
determine whether the record is an overflow record, you should 
test the exception code field of the DECB. 

After you test the exception code field of the DECB, you need 
not set it to 0. If you have used a READ KU macro instruction 
and if you plan to use the same DECB again to rewrite the 
updated record using a WRITE K macro instruction, you should not 
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sot the field to 0. If you do, your record may not be rewritten 
properly. 

To update existing records, you must use the READ KU and WRITE K 
combination. Because READ KU implies that the record will be 
rewritten in the data set, the system retains the DECB and the 
buffer used in the READ KU and uses them when the record is 
written. If you decide not to write the record, you should use 
the same DECB in another read or write macro instruction or 
issue a FREEDBUF macro instruction if dynamic buffering was 
used. If you issue several READ KU or WRITE K macro instructions 
before checking the first one, you may destroy some of your 
updated records unless the records are from different blocks. 

If there is the possibility that your task and another task will 
be simultaneously accessing the same data set, or the same task 
has two or more DCBs opened for the same data set, you should 
use the DCB integrity feature. You specify the DCB integrity 
feature by coding DISP=SHR in your DD statement. In this way you 
ensure that the DCB fields are maintained for your program to 
process the data set correctly. If you do not use DISP=SHR and 
more than one DCB is open for updating the data set, the results 
are unpredieatable. 

If you specify DISP=SHR, you must also issue an ENQ for the data 
set before each input/output request and a DEQ upon completion 
of the request. All users of the data set must use the same 
gname and rname operands for ENQ. For example, the users might 
use the data set name as the g name operand. For more information 
about using ENQ and DEQ, see 0S/VS2 Supervisor Services and 
Macro Instructions . 

When you are using scan mode with QI5AM and you want to issue 
PUTX, issue an ENQ on the data set before processing it and a 
DEQ after processing is complete. ENQ must be issued before the 
SETL macro instruction, and DEQ must be issued after the ESETL 
macro instruction. When you are using BISAM to update the data 
set, do not modify any DCB fields or issue a DEQ until you have 
issued CHECK or WAIT. 

SHARING A BISAM DCB BETWEEN RELATED TASKS * When a task using 
BISAM processes a data set whose DCB is defined and opened by a 
related task, the task must issue an ENQ on the DCB before an 
input/output request is issued and must issue a DEQ after the 
WAIT or CHECK for the input/output request is issued. If the 
task does not enqueue the DCB and any of its related tasks 
terminates abnormally, the task may enter a wait state or a 
program check may occur. See QS/VS2 Supervisor Services and 
Macro Instruction for more information on the ENQ and DEQ macro 
instructions and on multitasking. 

For subtasking, I/O requests should be issued by the task which 
owns the DCB or a task which will remain active as long as the 
DCB is open. If the task that issued the I/O request terminates, 
the storage used by its data areas (such as IOBs may be freed or 
queuing switches in the DCB work area may be left set on, 
causing another task issuing an I/O request to the DCB to 
program check or to enter the wait state. For example, if a 
subtask issues and completes a READ KU I/O request, the IOB 
which was created by the subtask is attached to the DCB update 
queue. If that subtask terminates, and subpool zero is not 
shared with the subtask owning the DCB, the IOB storage area is 
freed and the integrity of the ISAM update queue is destroyed. A 
request from another subtask, attempting to use that queue, may 
cause unpredictable abends. As another example, if a WRITE KEY 
NEW is in process when the subtask terminates, 

’’WRITE-KEY-NEW-IN-PROCESS” bit is left set on. if another I/O 
request is issued to the DCB, the request is queued but cannot 
proceeed. 

DIRECT UPDATE WITH EXCLUSIVE CONTROL—INDEXED SEQUENTIAL DATA 

SET J In the example shown in Figure 57 on page 121 the 
previously described data set is to be updated directly with 
transaction records on tape. The input tape records are 30 
characters long, the key is in positions 1-10, and the update 
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information is in positions 11-30. The update information 
replaces data in positions 31-50 of the indexed sequential data 
record. 



//INDEXDD 

DD 

DSNAME=SLATE.DICT,DCB=(DSORG 

= IS,BUFNO = l, ...),— 


//TAPEDD 

DD 

— — “ 



ISUPDATE 

START 

0 



NEXTREC 

GET 

TPDATA,TPRECORD 




ENQ 

(RESOURCE,ELEMENT,E,,SYSTEM) 




READ 

DECBRW,KU,,’S’,MF=E 

Read into dynamically 
obtained buffer 



WAIT 

ECB=DECBRW 




TM 

DECBRW+24,X’FD’ 

Test for any condition 



BM 

RDCHECK 

but overflow 



L 

3,DECBRW+16 

Pick up pointer to record 



MVC 

ISUPDATE-ISRECORD 
(L’UPDATE,3),UPDATE 

Update record 



WRITE 

DECBRW,K,MF=E 




WAIT 

ECB=DECBRW 




TM 

DECBRW+24,X’FD’ 

Any errors? 



BM 

WRCHECK 




DEQ 

(RESOURCE,ELEMENT,,SYSTEM) 




B 

NEXTREC 



RDCHECK 

TM 

DECBRW + 24, X’ 80 1 

No record found 



BZ 

ERROR 

If not, go to error routine 



FREEDBUF 

DECBRW,K,ISDATA 

Otherwise, free buffer 



MVC 

ISKEY,KEY 

Key placed in ISRECORD 



MVC 

ISUPDATE,UPDATE 

Updated information placed 


X 

WRITE 

DECBRW,KN,,WKNAREA,’S',MF=E 

in ISRECORD 

Add record to data set 

■ 


WAIT 

ECB=DECBRW 


( 


TM 

DECBRW+24,X’FD* 

Test for errors 

V. 


BM 

ERROR 




DEQ 

(RESOURCE,ELEMENT,,SYSTEM) 

Release exclusive control 



B 

NEXTREC 



WKNAREA 

DS 

4F 

BISAM WRITE KN work field 


ISRECORD 

DS 

0CL50 

50-byte record from ISDATA 



DS 

CL 1 9 

DCB First part of ISRECORD 


ISKEY 

DS 

CLIO 

Key field of ISRECORD 



DS 

CL 1 

Part of ISRECORD 


ISUPDATE 

DS 

CL20 

Update area of ISRECORD 



ORG 

ISUPDATE 

Overlay ISUPDATE with 


TPRECORD 

DS 

0CL30 

TPRECORD 30-byte record from 


KEY 

DS 

CLIO 

TPDATA DCB Key for locating 


UPDATE 

DS 

CL20 

ISDATA record Update 


RESOURCE 

DC 

CL8’SLATE’ 

information or new data 


ELEMENT 

DC 

C’DICT’ 




READ 

DECBRW,KU,ISDATA,*S',’S’,KEY,MF=L 


ISDATA 

DCB 

DDNAME=INDEXDD,DS0RG=IS,MACRF=(RUS,WUA), C 




MSHI=INDEX,SMSI=2000 



TPDATA 

DCB 

— 


* 

INDEX 

DS 

2000C 



Figure 57. 

Directly 

Updating an Indexed Sequential Data Set 


Exclusive control of the data set is requested since more than 
one task may be referring to the data set at the same time. 
Notice that exclusive control is released after each block is 
written to avoid tying up the data set until the update is 
completed. 


Note the use of the FREEDBUF macro instructioi 
Usually the FREEDBUF macro instruction has twi 


in Fi gure 57. 
functions • 
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• To indicate to the ISAM routines that a record that has been 
read for update will not be written back 

• To free a dynamically obtained buffer 

In Figure 57 on page 121/ since the read operation was 
unsuccessful/ the FREEDBUF macro instruction frees only the 
dynamically obtained buffer. 

The first function of FREEDBUF allows you to read a record for 
update and then decide not to update it without performing a 
WRITE for update. You can use this function even when your READ 
macro instruction does not specify dynamic buffering/ provided 
that you have included S Cfor dynamic buffering) in the MACRF 
field of your READ DCB. 


You can effect an automatic FREEDBUF simply by reusing the DECB/ 
that i5/ by issuing another READ or a WRITE KN to the same DECB. 
You should use this feature whenever possible/ since it is more 
efficient than FREEDBUF. For example/ in Figure 57 on page 
121/the FREEDBUF macro instruction could be eliminated/ since 
the WRITE KN addressed the same DECB as the READ KU. 

For an indexed sequential data set with variable-length records/ 
you may make three types of updates by using the basic access 
technique. You may read a record and write it back with no 
change in its length, simply updating some part of the record. 
You do this with a READ KU followed by a WRITE K, the same way 
you update fixed-length records. Two other methods for updating 
variable-length records use the WRITE KN macro instruction and 
allow you to change the record length. 

In one method, a record read for update (by a READ KU) may be 
updated in a manner that will change the record length and then 
be written back with its new length by a WRITE KN. In the second 
method, you may replace a record with another record having the 
same key and possibly a different length using the WRITE KN 
macro instruction. To replace a record, it is not necessary to 
have first read the record. 


In either method, when changing the record length, you must 
place the new length in the DECBLGTH field of the DECB before 
issuing the WRITE KN macro instruction. If you use a WRITE KN 
macro instruction to update a variable-length record that has 
been marked for deletion, the first bit (no record found) of the 
exceptional condition code field (DECBEXC1) of the DECB is set 
on. If this condition is found, the record must be written using 
a WRITE KN with nothing specified in the DECBLGTH field. 


Do not try to use the DECBLGTH field to determine the length of 
a record read, because DECBLGTH is for use with writing records, 
not reading them. If you are reading fixed-length records, the 
length of the record read is in DCBLRECL, and if you are reading 
variable-length records, the length is in the record descriptor 
word (RDW). 

DIRECT UPDATE—INDEXED SEQUENTIAL DATA SET WITH VARIABLE-LENGTH 

RECORDS: In Figure 58, an indexed sequential data set with 
variable-length records is updated directly with transaction 
records on tape. The transaction records are of variable length 
and each contains a code identifying the type of transaction. 
Transaction code 1 indicates that an existing record is to be 
replaced by one with the same key; 2 indicates that the record 
is to be updated by appending additional information, thus 
changing the record length; 3 or greater indicates that the 
record is to be updated with no change to its length. For this 
example, the maximum record length of both data sets is 256 
bytes. The key is in positions 6-15 of the records in both data 
sets. The transaction code is in position 5 of records on the 
transaction tape. The work area (REPLAREA) size is equal to the 
maximum record length plus 16 bytes. 




* 
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//INDEXDD 

DD 

DSNAME=SLATE.DICT,DCB=(DS0RG=IS,BUFN0=1,...),- 

//TAPEDD 

DD 

— 


ISUPDVLR 

START 

0 


NEXTREC 

GET 

TPDATA,TRANAREA 



CLI 

TRANCODE,2 

Determine if replacement or 

X 

BL 

REPLACE 

other transaction 

Branch if replacement 


READ 

DECBRW,KU,,’S','S *,MF=E 

Read record for update 


CHECK 

DECBRW,DS0RG=IS 

Check exceptional conditions 


CLI 

TRANCODE,2 

Determine if change or append 


BH 

CHANGE 

Branch if change 

K CODE TO 

MOVERECORD INTO REPLACEA+16 AND 

APPEND DATA FROM TRANSACTION 

X RECORD 

MVC 

DECBRW+6(2),REPLAREA+16 

move new length from RDW 

X 

WRITE 

DECBRW,KN,,REPLAREA,MF=E 

into DECBLGTH CDECB+6) 

Rewrite record with 

X 

CHECK 

DECBRW,DS0RG=IS 

changed length 


B 

NEXTREC 


CHANGE 




K CODE TO 

CHANGE 1 

FIELDS OR UPDATE FIELDS OF 

THE RECORD 


WRITE 

DECBRW,K,MF=E 

Rewrite record with no 

X 

CHECK 

DECBRW,DS0RG=IS 

change of length 


B 

NEXTREC 


REPLACE 

MVC 

DECBRW+6C2),TRANAREA 

Move new length from RDW 

X 



into DECBLGTH (DECB+6) 


WRITE 

DECBRW,KN,,TRANAREA-16,MF=E Write transaction record 

X 



as replacement for record 

X 

CHECK 

DECBRW,DS0RG=IS 

with the same key 


B 

NEXTREC 


CHECKERR 


SYNAD routine 

REPLAREA 

DS* 

CL272 


TRANAREA 

DS 

CL4 


TRANCODE 

DS 

CLI 


KEY 

DS 

CLIO 


TRANDATA 

DS 

CL241 



READ 

DECBRW,KU,ISDATA,'S','S’ 

,KEY,MF=L 

ISDATA 

DCB 

DDNAME=INDEXDD,DSORG=IS, 

MACRF=(RUSC,WUAC),SYNAD=CHECKERR 

TPDATA 

DCB 



Figure 58 

. Directly Updating an Indexed Sequential Data Set with 


Variable-Length Records 



PROCESSING A DIRECT DATA SET 


In a direct data set/ there is a relationship between a control 
number or identification of each record and its location on the 
direct-access volume. This relationship allows you to gain 
access to a record without an index search. You determine the 
actual organization of the data set. If the data set has been 
carefully organized, location of a particular record takes less 
time than with an indexed sequential data set. 

The DSORG parameter of the DCB macro specifies the type of 
processing to be performed, while DSORG in the DD statement 
specifies the organization of the data set. 
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Although you can process a direct data set sequentially using 
either the queued access technique or the basic access 
technique, you cannot read record keys using the queued access 
technique. When you use the basic access technique, each unit of 
data transmitted between virtual storage and an I/O device is 
regarded by the system as a record. If, in fact, it is a block, 
you must perform any blocking or deblocking required. For that 
reason, the LRECL field is not used when processing a direct 
data set. Only BLKSIZE must be specified when you add or update 
records on a direct data set. 

If dynamic buffering is specified for your direct data set, the 
system will provide a buffer for your records. If dynamic 
buffering is not specified, you must provide a buffer for the 
system to use. 

As indicated in the discussion of direct-access devices, record 
keys are optional. If they are specified, they must be used for 
every record and must be of a fixed length. 


ORGANIZING A DIRECT DATA SET 

In developing the organization of your data set, you can use 
direct addressing . When direct addresses are used, the location 
of each record in the data set is known. 

If format-F records with keys are being written, the key of each 
record can be used to identify the record. For example, a data 
set with keys ranging from 0 to 4999 should be allocated space 
for 5000 records. Each key relates directly to a location that 
you can refer to as a relative record number. Therefore, each 
record should be assigned a unique key. If identical keys are 
used it is possible, during periods of high CPU and channel 
activity, to skip the desired record and retrieve the next 
record on the track. The main disadvantage of this type of 
organization is that records may not exist for many of the keys 
even though space has been reserved for them. 

Space could be allocated on the basis of the number of records 
in the data set rather than on the range of keys. This type of 
organization requires the use of a cross-reference table. When a 
record is written in the data set, you must note the physical 
location either as an actual address or as a relative track and 
record number. The addresses must then be stored in a table that 
is searched when a record is to be retrieved. Disadvantages are 
that cross-referencing can be used efficiently only with a small 
data set, storage is required for the table, and processing time 
is required for searching and updating the table. 

A more common, but somewhat complex, technique for organizing 
the data set involves the use of indirect addressing. In 
indirect addressing, the address of each record in the data set 
is determined by a mathematical manipulation of the key. This 
manipulation is referred to as randomizing or conversion. Since 
a number of randomizing procedures could be used, no attempt is 
made here to describe or explain those that might be most 
appropriate for your data set. 


REFERRING TO A RECORD IN A DIRECT DATA SET 

Once you have determined how your data set is to be organized, 
you must consider how the individual records will be referred to 
when the data set is updated or new records are added. This is 
important for determining whether a return address will be 
required when the data is created and, if so, in what form the 
return address will be used. The record identification can be 
represented in any of the following forms’- 
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RELATIVE BLOCK ADDRESS : You specify the relative location of the 
record (block) within the data set as a 3-byte binary number. 
This type of reference can be used only with format-F records. 
The system computes the actual track and record number. The 
relative block address of the first block is 0. 

RELATIVE TRACK ADDRESS •* You specify the relative track as a 
2-byte binary number and the actual record number on that track 
as a 1-byte binary number. The relative track address of the 
first track is 0. 

RELATIVE TRACK OR BLOCK ADDRESS AND ACTUAL KEY-* In addition to 
the relative track or block address, you specify the address of 
a virtual-storage location containing the record key. The system 
computes the actual track address and searches for the record 
with the correct key. 

ACTUAL ADDRESS: You supply the actual address in the standard 
8-byte form—MBBCCHHR. Remember that the use of an actual 
address may force you to indicate that the data set is 
unmovable. 

EXTENDED SEARCH: You request that the system begin its search 
with a specified starting location and continue for a certain 
number of records or tracks. This same option can be used to 
request a search for unused space in which a record can be 
added. 

To use the extended search option, you must indicate in the DCB 
the number of tracks (including the starting track) or records 
(including the starting record) that are to be searched. If you 
indicate a number of records, the system may actually examine 
more than this number. In searching a track, the system searches 
the whole track (starting with the first record); it therefore 
may examine records that precede the starting record or follow 
the ending record. 

If the DCB specifies a number equal to or greater than the 
number of tracks allocated to the data set or the number of 
records within the data set, the entire data set is searched in 
the attempt to satisfy your request. 

EXCLUSIVE CONTROL FOR UPDATING: When more than one task is 
referring to the same data set, exclusive control of the block 
being updated is required to prevent simultaneous reference to 
the same record. Rather than issuing an ENQ macro instruction 
each time you update a block, you can request exclusive control 
through the MACRF field of the DCB and the type operand of the 
READ macro. The coding example in Figure 61 on page 129 
illustrates the use of exclusive control. After the READ macro 
instruction is executed, your task has exclusive control of the 
block being updated. No other task in the system requesting 
access to the block is given access until the operation started 
by your WRITE macro is complete. If, however, the block is not 
to be written, you can release exclusive control using the RELEX 
macro instruction. 

FEEDBACK OPTION-* This option specifies that the system provide 
the address of the record requested by a READ or WRITE macro 
instruction. This address may be in the same form that was 
presented to the system in the READ or WRITE macro instruction, 
or as an 8-byte actual address. This option can be specified in 
the OPTCD parameter of the DCB and in the READ or WRITE macro 
instruction. If this option is omitted from the DCB but is 
requested in a READ or WRITE macro instruction, an 8-byte actual 
address is returned to the user. 

The feedback option is automatically provided for a READ macro 
instruction requesting exclusive control for updating. This 
feedback will be in the form of an actual address (MBBCCHHR) 
unless feedback was specified in the OPTCD field of the DCB. In 
this case, feedback is returned in the format of the addressing 
scheme used in the problem program (an actual or a relative 
address). When a WRITE or RELEX macro instruction is issued 
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(which releases the exclusive control that was gotten for the 
READ request), the system will assume that the addressing scheme 
used for the WRITE or RELEX macro instruction is in the same 
format as the addressing scheme used for feedback in the READ 
macro instruction. 


CREATING A DIRECT DATA SET 

Once the organization of a direct data set has been determined, 
the process of creating it is almost identical to that of 
creating a sequential data set. The BSAM DCB macro instruction 
should be used with the WRITE macro instruction (the form used 
to create a direct data set). The following parameters must be 
specified in the DCB macro instruction 5 

• DS0RG=PS or P5U 

• DEVD=DA or omitted 

• MACRF=WL 

The DD statement must indicate direct-access (DS0RG=DA or DAU). 
If keys are used, a key length (KEYLEN) must also be specified. 
Record length (LRECL) need not be specified but may be used to 
provide compatibility with sequential access method processing 
of this data set. 

It is possible to create a direct data set using QSAM (no keys 
allowed) or BSAM (with or without keys and the DCB specifies 
MACRF = W). However, this method is not recommended because when 
you access this direct data set, you cannot request a function 
which requires the information in the capacity record (RO) data 
field. For example, the following restrictions would apply 5 

• Variable-length, undefined-length, or variable-length 
spanned record processing is not allowed. 

• The WRITE add function with extended search for fixed-length 
records (with or without track overflow) is not allowed. 

If a VIO data set is opened for processing with the extended 
search option, the DEBENDCC and DEBENDHH fields of the DEB will 
reflect the real address of the last record written during the 
BDAM create step. This is necessary to prevent BDAM from 
searching unused tracks. The information needed to determine the 
data set size is written in the DSCB during the close of the DCB 
used in the create step. Therefore, if this data set is being 
created and processed by the same program, and the DCB used for 
creating the data set has not been closed before opening the DCB 
to be used for processing, the resultant beginning and ending 
CCHH will be equal. 

If a direct data set is created and updated or read within the 
same job step, and the OPTCD parameter is used in the creation, 
updating, or reading of the data set, different DCBs and DD 
statements should be used. 

If you are using direct addressing with keys, you can reserve 
space for future format-F records by writing a dummy record. To 
reserve or truncate a track for format-U or format-V records, 
write a capacity record. The capacity record (RO) contains a 
7-byte data field (CCHHRLL) where CCHHR is the ID of the last 
record on the track, and LL is the number of unused bytes on the 
track. If a WRITE SZ macro is issued for a track with no 
records, R is zero and LL is the entire length of the track. 

Format-F records are written sequentially as they are presented. 
When a track is filled, the system automatically writes the 
capacity record and advances to the next track. Because of the 
form in which relative track addresses are recorded, direct data 
sets whose records are to be identified by means other than 
actual address must be limited in size to no more than 65,536 
tracks for the entire data set. 
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TAPE-TO-DISK—DIRECT DATA SET: In the example problem in 
Figure 59, a tape containing 204-byte records arranged in key 
sequence is used to create a direct data set. A 4-byte binary 
key for each record ranges from 1000 to 8999, so space for 8000 
records is requested. 


//DAOUTPUT DD DSNAME=SLATE.INDEX.WORDS,DCB=CDS0RG=DA, C 

// BLKSIZE=200,KEYLEN=4,RECFM=F),SPACE=(204,8000),- 


//TAPINPUT 

DD 

— 



DIRECT 

START 





... 

9,=F f 1000 * 




OPEN 

CDALOAD,(OUTPUT),TAPEDCB) 




LA 

10,COMPARE 



NEXTREC 

GET 

TAPEDCB 




LR 

2,1 



COMPARE 

C 

9,0(2) 

Compare key of input 

against 

X 

BNE 

DUMMY 

control number 



WRITE 

DECB1,SF,DALOAD,(2) 

Write data record 



CHECK 

DECB1 




AH 

9,=H*1' 




B 

NEXTREC 



DUMMY 

C 

9,=F’8999’ 

Have 8000 records been written? 


BH 

ENDJOB 




WRITE 

DECB2,SD,DALOAD,DUMAREA 

Write dummy 



CHECK 

DECB2 




AH 

9,=H’1 ’ 




BR 

10 



INPUTEND 

LA 

10,DUMMY 




BR 

10 



ENDJOB 

CLOSE 

(TAPEDCB,,DALOAD) 



DUMAREA 

DS* 

8F 



DALOAD 

DCB 

DSORG=PS,MACRF=(WL),DDNAME 
DEVD=DA,SYNAD=CHECKER,- 

=DA0UTPUT, 

C 

TAPEDCB 

DCB 

EODAD=INPUTEND,MACRF=(GL), 



Figure 59. 

Creating a Direct Data Set 




ADDING OR UPDATING RECORDS ON A DIRECT DATA SET 

The techniques for adding records to a direct data set depend on 
the format of the records and the organization used. 

FORMAT-F WITH KEYS: Adding a record amounts to essentially an 
update by record identification. The reference to the record can 
be made by either a relative block address or a relative track 
address. 

If you attempt to add a record by relative block address, the 
system converts the address to a relative track address. That 
track is searched and the new record written in place of the 
first dummy record on the track. If there is no dummy record on 
the track, you are informed that the write operation did not 
take place. If you request the extended search option, the new 
record will be written in place of the first dummy record found 
within the search limits you specify. If none is found, you are 
notified that the write operation could could not take place. In 
the same way, a reference by relative track address causes the 
record to be written in place of the first dummy record found on 
that track or the first within the search limits, if requested. 
If extended search is used, the search begins with the first 
record on the track. Without extended search, the search may 
start at any record on the track. Therefore, records which were 
added to a track are not necessarily located on that track in 
the same sequence in which they were written. 
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FORMAT-F WITHOUT KEYS: Here too, adding a record is really 
updating a dummy record already in the data set. The main 
difference is that dummy records cannot be written automatically 
when the data set is created. You will have to use your own 
method for flagging dummy records. The update form of the WRITE 
macro instruction (MACRF=W) must be used rather than the add 
form (MACRF=WA). 

You will have to retrieve the record first (using a READ macro 
instruction), test for a dummy record, update, and write. 

FORHAT-V OR FORMAT-U WITH KEYS: The technique used to add 
records in this case depends on whether records are located by 
indirect addressing or a cross-reference table. If indirect 
addressing is used, you must at least initialize each track 
(write a capacity record) even if no data is actually written. 
That way the capacity record indicates how much space is 
available on the track. If a cross-reference table is used, you 
should exhaust the input and then initialize enough succeeding 
tracks to contain any additions that might be required. 

To add a new record, use a relative track address. The system 
examines the capacity record to see if there is room on the 
track. If there is, the new record is written. Under the 
extended search option, the record is written in the first 
available area within the search limit. 

FORMAT-V OR FORMAT-U WITHOUT KEYS: Because a record of this type 
does not have a key, you can refer to the record only by its 
relative track or actual address (direct addressing only). When 
you add a record to this data set, you must retain the relative 
track or actual address data (for example, by updating your 
cross-reference table). The extended search option is not 
allowed because this option requires keys. 


//DIRADD 

DD 

DSNAME=SLATE.INDEX.WORDS 

> 

//TAPEDD 

DD 

— 


DIRECTAD 

START 




OPEN 

(DIRECT,(OUTPUT),TAPEIN) 


NEXTREC 

GET 

TAPEIN,KEY 



L 

4,KEY 

Set up relative record 


SH 

4,=H’ 1000 ' 



ST 

4,REF 



WRITE 

DECB,DA,DIRECT,DATA,’S’, 

KEY,REF+1 


WAIT 

ECB=DECB 



CLC 

DECB+1(2),=X»0000* 

Check for any errors 


BE 

NEXTREC 



Check error bits and take required action 


DIRECT 

DCB 

DDNAME=DIRADD,DSORG=DA,RECFM=F,KEYLEN=4,BLKSIZE=200 

MACRF=(WA) 

TAPEIN 

DCB 

— 

KEY 

DS 

F 

DATA 

DS 

CL200 

REF 

DS 

F 


Figure 60. Adding Records to a Direct Data Set 


C 


TAPE-TQ-DISK ADD—DIRECT DATA SET: The example in Figure 60 
involves adding records to the data set created in the last 
example. Notice that the write operation adds the key and the 
data record to the data set. If the existing record is not a 
dummy record, an indication is returned in the exception code of 
the DECB. For that reason, it is better to use the WAIT macro 
instruction instead of the CHECK macro instruction to test for 
errors or exceptional conditions. 
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TAPE-TO-DISK UPDATE—DIRECT DATA SET: The example in Figure 61 
is similar to that in Figure 60 on page 128, but involves 
updating rather than adding. There is no check for dummy 
records. The existing direct data set contains 25,000 records 
whose 5-byte keys range from 00001 to 25000. Each data record is 
100 bytes long. The first 30 characters are to be updated. Each 
input tape record consists of a 5-byte key and a 30-byte data 
area. Notice that only data is brought into virtual storage for 
updating. 

I When you are updating variable length records, you should use 

I the same length to read and write a record. 


//DIRECTDD DD DSNAME=SLATE. INDEX.WORDS ,— 

//TAPINPUT DD 


DIRUPDAT 

START 



OPEN 

(DIRECT,(UPDAT),TAPEDCB) 

NEXTREC 

GET 

TAPEDCB,KEY 


PACK 

KEY,KEY 


CVB 

3,KEYFIELD 


SH 

3,=H*1' 


ST 

3,REF 


READ 

DECBRD,DIX,DIRECT, f S',’S',0,REF+1 


CHECK 

DECBRD 


L 

3,DECBRD+12 


MVC 

0(30,3),DATA 


ST 

3,DECBWR+12 


WRITE 

DECBWR,DIX,DIRECT,’S', f S’,0,REF+1 


CHECK 

DECBWR 


B 

NEXTREC 

KEYFIELD 

DS* 

0D 


DC 

XL3 1 0 1 

KEY 

DS 

CL5 

DATA 

DS 

CL30 

REF 

DS 

F 

DIRECT 

DCB 

DS0RG=DA,DDNAME=DIRECTDD,MACRF=(RISXC,WIC), 


OPTCD=RF,BUFNO=1,BUFL=10Q 

TAPEDCB 

DCB 

— 


Figure 61. Updating a Direct Data Set 


CONSIDERATION FOR USER LABELS: User labels, if desired, must be 
created when the data set is created. They may be updated, but 
not added or deleted, during processing of a direct data set. 
When creating a multi volume direct data set using BSAM, you 
should turn off the header exit entry after OPEN and turn on the 
trailer label exit entry just before issuing the CLOSE. This 
eliminates the end-of-volume exits. The first volume, containing 
the user label track, must be mounted when the data set is 
closed. If you have requested exclusive control, OPEN and CLOSE 
will ENQ and DEQ to prevent simultaneous reference to user 
labels. 

CONSIDERATION FOR USING THE 2305 FIXED HEAD STORAGE: When a data 
set on a 2305 device is to be used by several tasks 
simultaneously, or when overlapping I/O (successive WRITEs 
issued without an intervening CHECK or WAIT) is used, the 
following combination may produce overlaying of records: 

• WRITE-add processing 

• Fixed records with or without track overflow 
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PART 3? DATA SET DISPOSITION AND SPACE ALLOCATION 


ALLOCATING SPACE ON DIRECT-ACCESS VOLUMES 


When direct-access storage space is required for a data set, you 
specify the amount of space needed and the device type, and the 
operating system selects the device and allocates the space 
accordingly. This arrangement provides for flexible and 
efficient use of devices and available storage space, and 
relieves you of considering the details involved in efficient 
space control. 

Before a direct-access volume can be used for data storage, it 
must be initialised by either of the utility programs IBCDASDI 
or IEHDASDR. The utilities’ functions include in part : 

• Creating the standard 80-byte volume label and writing it on 
cylinder 0, track 0, of the volume. 

• Initialising the volume table of contents (VTOC). The 
location of the VTOC depends on the conventions your 
installation uses in initialising the volume. 

• Writing the home address (HA) and capacity record (R0) for 
each track. 

• Checking tracks and making alternate track assignments if 
necessary. 

When the data set is to be stored on a direct-access volume, you 
must supply, in the DD statement, control information 
designating the amount of space to be allocated and the manner 
in which it is to be allocated. 

Note: IEHDASDR and IBCDASDI cannot be used for an MSS 3330 
virtual volume. The Access Method Services utility, CREATEV, 
must be used. See QS/VS Mass Storage System (MSS) Services for 
Space Management for a description of the CREATEV command. 


SPECIFYING SPACE REQUIREMENTS 

The amount of space required can be specified in blocks, tracks, 
or cylinders. If you want to maintain device independence, 
specify your space requirements in blocks. If your request is in 
tracks or cylinders, you must be aware of such device 
considerations as cylinder and track capacity. 

Cylinder allocation allows faster input/output of sequential 
data sets than does track allocation. The exceptions are reading 
records in fixed standard format on a non-RPS device without 
using chained scheduling, and writing any records without using 
chained scheduling. Note that these two exceptions do not apply 
to 574Q-AM3. 

ALLOCATION BY BLOCKS: When the amount of space required is 
expressed in blocks, you must specify the number and average 
length of the blocks within the data set, as in this example 1 

// DD SPACE=(300,(5000,100)), . . . 

300 = average block length in bytes 
5000 = primary quantity (number of blocks) 

100 = secondary quantity, to be allocated if the primary 
quantity is not sufficient (in blocks) 

Note that when average block length and secondary space 
allocation are being used, the BLKSIZE parameter specified must 
be equal to the maximum block length. 
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From this information# the operating system estimates and 
allocates the number of tracks required. Space is always in 
whole tracks. You may also request that the space allocated for 
a specific number of blocks begin and end on cylinder 
boundaries. 

You must be certain that both the quantity and the increment are 
large enough to contain the largest block to be written. 
Otherwise# all of the space requested is allocated but erased as 
the system tries to find a space large enough for the record. 

ALLOCATION BY TRACKS OR CYLINDERS: The amount of space required 
can be expressed in tracks or cylinders# as in these examples: 

// DD SPACE=(TRK#(100#5))# . . . 

// DD SPACE=CCYL,<3,1))# . . . 

ALLOCATION BY ABSOLUTE ADDRESS: If the data set contains 
location-dependent information in the form of an absolute track 
address (MBBCCHHR)# space should be requested with respect to 
the number of tracks and the beginning address# as in this 
example : 

// DD SPACE=(ABSTR#C500,20)),UNIT=2314# . . . 

where 500 tracks are required# beginning at relative track 20# 
which is cylinder 1# track 0. 

ALLOCATION OF MASS STORAGE SYSTEM (MSS) VIRTUAL VOLUMES: When 
the data set is to be stored on an MSS virtual volume# a volume 
group (MSVGP) parameter may be specified instead of using the 
SPACE parameter on the DD card. Before the MSVGP parameter can 
be used# the volume group must be identified to MSS by the 
utility program IDCAMS. 

Allocation of MSS virtual volume space should be in multiples of 
cylinders with secondary allocation a multiple of the primary to 
insure maximum space usage and minimum fragmentation. 

ADDITIONAL SPACE ALLOCATION OPTIONS: The DD statement provides 
you with a great deal of flexibility in specifying space 
requirements. These options are described in detail in QS/VS2 
JCL. 


ESTIMATING SPACE REQUIREMENTS 

To determine how much space your data set requires# you must 
consider these variables for the device type : 

• Track capacity 

• Tracks per cylinder 

• Cylinders per volume 

• Data length (blocksize) 

• Key length 

• Device overhead 

Figure 62 on page 132 lists the physical characteristics of a 
number of direct-access storage devices. 
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Maximum 


Number 



Volume 

Block size 

Tracks per 

of 

Total 

Device 

Type 

per Track 1 

Cylinder 

cylinders 2 

Capacity 1 , 2 

2305-1 

Drum 

14136 

8 

48 

5,428,224 

2305-2 

Drum 

14660 

8 

96 

11,258,880 

2314/2319 

Di sk 

7294 

20 

200 

29,176,000 

3330/3333 5 






(Model 1) 

Di sk 

13030 

19 

404 

100,018,280 

3330/3333 






(Model 11) 

Disk 

13030 

19 

808 

200,036,560 

3340/3344 4 

Di sk 

8368 

12 

696 





(70 

megabytes) 

69,889,536 





348 





(35 

megabytes) 

34,944,768 

3350 

Di sk 

19069 

30 

555 

317,498,850 

3375 

Di sk 

32760 s 

12 

959 

409,868,928 

3380 

Di sk 

32760 s 

15 

885 

630,243,900 


1 Capacity indicated in bytes (when RO is used by the IBM programming system). 

2 Excluding alternate cylinders. 

3 The Mass Storage System (MSS) virtual volumes assume the characteristics of 
the 3330/3333, Model 1. 

4 The 3344 is functionally equivalent to the 3340 Model 70. 

5 The largest record that can be written on a track is 35,616 for the 3375 and 
47,476 for the 3380. However, for both devices, the largest block size 
supported by the standard access methods is 32,760. 

Figure 62. Direct-Access Storage Device Capacities 


The term device overhead refers to the space required on each 
track for hardware data, that is, address markers, count areas, 
gaps between records, record 0, etc. Device overhead varies with 
each device and depends also on whether the blocks are written 
with keys. To compute the actual space required for each block, 
including device overhead, you can use the formulas in 
Figure 63 on page 133. Note that any fraction of a byte must be 
ignored. For example, if the formula gives 15.644 bytes, you 
must allocate 15 bytes. 
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Bytes Required by Each Data Block 


Device 

Track 

Cap 

Blocks With Keys 

Blocks without Keys 

2305-1 

14568 1 

634+Kl+DL 

432+DL 

2305-2 

14858 1 

289+KL+DL 

198+DL 

2314/2319 

7294 

146+(KL+DL)534/512 2 

101+(DL)534/512 3 

3330/3333 4 
(Model 1 
or 11) 

13165 

191+KL+DL 

135+DL 

3340/3344 

8535 1 

242+KL+DL 

167+DL 

3350 

19254 1 

267+KL+DL 

185+DL 

3375 

36000 

224+((KL+191)/32)(32)+((DL+191)/32)(32) 

224+( (DL + 19D/32) (32) 

3380 

47968 

256+((KL+267)/32)(32)+((DL+267)/32)(32) 

256+((DL+267)/32)(32) 

DL is data 

length, 




KL is key length. 

1 This value is different from the maximum block size per track because the 
formula for the last block on the track includes an overhead for this 
device. 

2 The formula for the last block on the track is 45+KL+DL. 

3 The formula for the last block on the track is DL. 

4 The Mass Storage System (MSS) virtual volumes assume the characteristics of 
the 3330/3333, Model 1. 

Figure 63. Direct-Access Device Overhead Formulas 


The formulas can be combined in the following way: 

If you intend to specify your space requirements in tracks (TRK) 
or cylinders (CYL), your estimate should be made as shown above. 
If you request absolute tracks (ABSTR), remember that you cannot 
allocate track 0, cylinder 0. The amount of space required for 
the VTOC will reduce the space available on the rest of the 
volume. 

If you specify your space requirements in average block length, 
the system performs the computations for you. 

Because a sequential data set and a direct data set are created 
in the same way, the estimate and specification of space 
requirements are identical. If you use the WRITE SZ macro 
instruction, your secondary allocation for a direct data set 
should be at least 2 tracks. Space allocation for a partitioned 
data set requires that you also consider the space used for the 
directory. Similarly, allocation for an indexed sequential data 
set requires that you consider the space needed for the prime 
area, index areas, and overflow areas. 


ALLOCATING SPACE FOR A PARTITIONED DATA SET 

What is the averag,e size of the members to be stored on your 
direct-access volume? How many members will fit on the volume? 
Will you need directory entries for the member names only or 
will aliases be used? How many? Will members be added or 
replaced frequently? All of these questions must be answered if 
you are to estimate your space requirements accurately and use 
the space efficiently. Note, too, that a partitioned data set 
cannot extend beyond one volume. 
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If your data set will be quite large, or you expect to do a lot 
of updating, it might be best to allocate a full volume. If it 
will be small or seldom subject to change, you should make your 
estimate as accurate as possible to avoid wasted space or wasted 
time used for recreating the data set. 

If the average member length is close to or less than the track 
length, the most efficient use of the direct-access storage 
space may be made with a block size of 1/3 or 1/2 the track 
length. For load modules, the linkage editor ignores the 
specified maximum block size and uses the maximum block size for 
the device. Program fetch always ignores BLKSIZE. It may be a 
good practice to indicate a block length equal to track 
capacity, for example, BLKSIZE=7294 for a 2314 disk. You might 
then ask for either 100 tracks, or 5 cylinders, thus allowing 
for 729,400 bytes of data. 

Assuming an average length of 70,000 bytes for each member, you 
need space for at least 10 directory entries. If each member 
also has an average of three aliases, space for an additional 30 
directory entries is required. 

Space for the directory is expressed in 256-byte blocks. Each 
block contains from 3 to 20 entries, depending on the length of 
the user data field. If you expect 40 directory entries, request 
at least 8 blocks. Any unused space on the last track of the 
directory is wasted unless there is enough space left to contain 
a block of the first member. Therefore, the most advisable 
request in this case would be for 17 blocks. 

Either of the following space specifications would cause the 
same size allocation for a 2314 disk: 

SPACE=(CYL,(5,,10) ) 

SPACE=(TRK,(100,,10)) 

The following example would result in allocation of 100 tracks 
for data, plus 1 track for directory space : 

SPACE = (7294,( 100 , , 10 )) 

Although a secondary allocation increment has been omitted in 
these examples, it could have been supplied to provide for 
extension of the member area. The directory size, however, 
cannot be extended. 


ALLOCATING SPACE FOR AN INDEXED SEQUENTIAL DATA SET 

An indexed sequential data set has three areas: prime, index, 
and overflow. Space for these areas can be subdivided and 
allocated as follows: 

• Prime area—If you request a prime area only, the system 
automatically uses a portion of that space for indexes, 
taking one cylinder at a time as needed. Any unused space in 
the last cylinder used for index will be allocated as an 
independent overflow area. More than one volume can be used 
in most cases, but all volumes must be for devices of the 
same device type. 

• Index area—You can request that a separate area be 
allocated to contain your cylinder and master indexes. The 
index area must be contained within one volume, but this 
volume can be on a device of a different type than the one 
that contains the prime area volume. If a separate index 
area is requested, you cannot catalog the data set with a DD 
statement. 

If the total space occupied by the prime area and index area 
does not exceed one volume, you can request that the 
separate index area be embedded in the prime area (to reduce 
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access arm movement) by indicating an index size in the 
SPACE parameter of the DD statement defining the prime area. 

If you request space for prime and index areas only, the 
system automatically uses any space remaining on the last 
cylinder used for master and cylinder indexes for overflow, 
provided the index area is on a device of the same type as 
the prime area. 

• Overflow area—Although you can request an independent 
overflow area, it must be contained within one volume. If no 
specific request for index area is made, then it will be 
allocated from the specified independent overflow area. 

To request that a designated number of tracks on each 
cylinder be used for cylinder overflow records, you must use 
the CYLOFL parameter of the DCB macro instruction. The 
number of tracks that you can use on each cylinder equals 
the total number of tracks on the cylinder minus the number 
of tracks needed for track index and for prime data, that 
i s * 

Usable tracks = total tracks - (track index tracks + prime 
data tracks) 

Note that when you create a 1-cylinder data set, ISAM reserves 1 

track on the last cylinder for the end-of-file filemark. 

When you request space for an indexed sequential data set, the 

DD statement must follow a number of conventions, as shown below 

and summarised in Figure 68 on page 156. 

• Space can be requested only in cylinders, SPACE=(CYL,(...)), 
or absolute tracks, SPACE=(ABSTR,(...)). If the absolute 
track technique is used, the designated tracks must make up 
a whole number of cylinders. 

• Data set organisation (DSORG) must be specified as indexed 
sequential (IS or ISU) in both the DCB macro instruction and 
the DCB parameter of the DD statement. 

• All required volumes must be mounted when the data set is 
opened; that is, volume mounting cannot be deferred. 

• If your prime area extends beyond one volume, you must 
indicate the number of units and volumes to be spanned, for 
example, UNIT=(2314,3),V0LUME=(,,,3). 

• You can catalog the data set using the DD statement 
parameter DISP=(,CATLG) only if the entire data set is 
defined by one DD statement; that is, if you did not request 
a separate index or independent overflow area. 
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1.Number 
of DD 

Statements 

Criteria 

2.Types 3 

of DD 

statements 

.Index 

Size 

Coded? 

Restrictions on 
Unit Types and 
Number of Units 
Requested 

Resulting- 
Arrangement 
of Areas 

( 

3 

INDEX 

PRIME 

OVFLOW 

— 

None 

Separate index* prime* 
and overflow areas. 


2 

INDEX 

PRIME 


None 

Separate index and prime 
areas. Any partially 
used index cylinder is 
used for independent 
overflow if the index 
and prime areas are on 
the same type of device. 
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Figure 64. Requests for Indexed Sequential Data Sets 


As your data set is created* the operating system builds the 
track indexes in the prime data area. Unless you request a 
separate index area or an embedded index area* the cylinder and 
master indexes are built in the independent overflow area. If 
you did not request an independent overflow area* the cylinder 
and master indexes are built in the prime area. 

If an error is encountered during allocation of a multivolume 
data set* the IEHPROGM utility program should be used to scratch 
the DSCBs of the data sets that were successfully allocated. The 
IEHLIST utility program can be used to determine whether or not 
part of the data set has been allocated. The IEHLIST utility 
program is also useful to determine whether space is available 
or whether identically named data sets exist before space 
allocation is attempted for indexed sequential data sets. These 
utility programs are described in OS/VS Uti1ities . 


Specifying a Prime Data Area 

To request that the system allocate space and subdivide it as 
required* you should code’- 


//ddname DD DSNAME=d5name*DCB=DS0RG=IS* 

// SPACE=(CYL,quantity* *CONTIG)*UNIT=unitname 

// DISP=(* KEEP)*- 
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You can accomplish the same type of allocation by qualifying 
your dsname with the element indication (PRIME). This element is 
assumed if omitted. It is required only if you request an 
independent index or overflow area; To request an embedded index 
area when an independent overflow area is specified, you must 
indicate DSNAME=dsname (PRIME). To indicate the size of the 
embedded index, you specify SPACE=(CYL,(quantity,,index size)). 


Specifying a Separate Index Area 

To request a separate index area, other than an embedded area as 
described above, you must use a separate DD statement. The 
element name is specified as (INDEX). The space and unit 
designations are as required. Notice that only the first DD 
statement can have a data definition name. The data set name 
(dsname) must be the same. 

//ddname DD DSNAME=dsname(INDEX),- 

// DD DSNAME=dsname(PRIME),- 


Specifying an Independent Overflow Area 

A request for an independent overflow area is essentially the 
same as for a separate index area. Only the element name, 

QVFLOW, is changed. If you do not request a separate index area, 
only two DD statements are required. 

//ddname DD DSNAME=dsname(INDEX),— 

// DD DSNAME=dsname(PRIME),- 

// DD DSNAME=dsname(QVFLOW),- 


Calculating Space Requirements for an Indexed Sequential Data set 

To determine the number of cylinders required for an indexed 
sequential data set, you must consider the number of blocks that 
will fit on a cylinder, the number of blocks that will be 
processed, and the amount of space required for indexes and 
overflow areas. When you make the computations, consider how 
much additional space is required for device overhead. Figure 62 
on page 132 and Figure 63 on page 133 show device capacities and 
overhead formulas. In the formulas that follow, the length of 
the last (or only) block, shown below as Bn, must include device 
overhead as given in Figure 63 on page 133. 

Blocks = 1 + ( Track capacity - Length of the last block ) 

(Length of other blocks) 

Bt = 1 + ((Ct~Bn)/Bi ) 

The following eight steps summarize calculation of space 
requirements for an indexed sequential data set. 

Step 1 

Once you know how many records will fit on a track and the 
maximum number of records you expect to create, you can 
determine how many tracks you will need for your data. 

Number of tracks required = Maximum number of blocks 

Blocks per track + 1 

ISAM load mode reserves the last prime data track for the 
filemark. 

Example? Assume that a 200,000 record part-of-speech dictionary 
is stored on an IBM 3330 Disk Storage, using the 3336 disk pack, 
as an indexed sequential data set. Each record in the dictionary 
has a 12-byte key (the word itself) and an 8-byte data area 
containing a part-of-speech code and control information. Each 
block contains 50 records; LRECL=20 and BLKSIZE=1000. Using the 
formula from Figure 63 on page 133, we find that each track will 
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contain 10 blocks or 500 records. A total of 401 tracks will be 
required for the dictionary. 

Bt = 1 + 13>165-(191+12+1000) = 1 + 11,962 = 1+9 = 10 

191+12+1000 1203 

Records per track = (10 blocks)(50 records per block) = 500 

Prime data tracks required (T) = 200,000 records _ +1 = 401 

500 records per track 

Step 2 

You will want to anticipate the number of tracks required for 
cylinder overflow areas. The computation is the same as for 
prime data tracks, but you must remember that overflow records 
are unblocked and a 10-byte link field is added. Remember, if 
you exceed the space allocated for any cylinder overflow area, 
an independent overflow area is required. Those records are not 
placed in another cylinder overflow area. 

Overflow records^l+ Track capacity-Lenoth of last overflow record 
per track (Ot) Length of other overflow records 

Ot = l+((Ct-Rn)/Ri) 

Example 5 Approximately 5000 overflow records are expected for 
the data set described in step 1. Since 56 overflow records will 
fit on a track, 90 overflow tracks are required. This is 90 
overflow tracks for 401 prime data tracks, or approximately 1 
overflow track for every 4 prime data tracks. Since the 3336 
disk pack has 19 tracks per cylinder, it would probably be best 
to allocate 4 tracks per cylinder for overflow. 

Ot = 1 + 13,165-C191+12+20+10 ) = 1 + 12,952 = 1+55 = 56 

191+12+20+10 233 

Overflow tracks required = 5000 records _ = 90 

56 records per track 

Overflow tracks per cylinder (Oc) = 4 

Step 3 

You will have to set aside space in the prime area for track 
index entries. There will be two entries (normal and overflow) 
for each track on a cylinder that contains prime data records. 

The data field of each index entry is always 10 bytes long. The 
key length corresponds to the key length for the prime data 
records. How many index entries will fit on a track? 

Index entries = 1 + Track capacity - Length of last index entry 

per track (It) Length of other index entries 

It = 1 + ((Ct-En)/Ei) 

Example 5 Again assuming use of a 3336 disk pack and records with 
12-byte keys, we find that 61 index entries will fit on a track. 

It = 1 + 13,165-(191+12+10 ) = 1 + 12,952 = 1+60 = 61 

191+(12+10) 213 


Step 4 

The number of tracks required for track index entries will 
depend on the number of tracks per cylinder and the number of 
track index entries per track. Any unused space on the last 
track of the track index can be used for any prime data records 
that will fit. 

Number of 

trk index = 2(Tracks per cylindei—overflow tracks per cvlinder) + l 
trks per Index entries per track+2 
cylinder 
(Ic) 
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Ic = (2(Tc-0c)+l)/CIt+2) 

Mote that for variable-length records or when a prime data 
record will not fit on the last track of the track index, the 
last track of the track index is not shared with prime data 
records. In such a case, if the remainder of the division is 
less than or equal to 2, drop the remainder. In all other cases, 
round the quotient up to the next integer. 

Example: The 3336 disk pack has 19 tracks per cylinder. You can 
fit 61 track index entries per track. Therefore, you need less 
than 1 track for each cylinder: 

Ic = 2(19-4)+! = 31 

61+2 63 

The space remaining on the track is (1-31/63) (13,165) = 6686 
bytes. 

This is enough for 6 blocks of prime data records. Since the 
normal number of blocks per track is 10, the blocks use 6/10 of 
the track, and the effective value of Ic is therefore 1-6/10 = 
2/5. 

Note that space is required on the last track of the track index 
for a dummy entry to indicate the end of the track index. The 
dummy entry consists of an 8-byte count field, a key field the 
same size as the key field in the preceding entries, and a 
10-byte data field. 

step 5 

Next you have to compute the number of tracks available on each 
cylinder for prime data records. You cannot include tracks set 
aside for cylinder overflow records. 

Prime data Tracks Overflow tracks Index tracks 

tracks per = per cylinder - per cylinder - per cylinder 

cylinder 

Pc = Tc-Oc-Ic 

Example: If you set aside 4 cylinder overflow tracks, and you 
require 2/5 of a track for the track index, 14 3/5 tracks are 
available on each cylinder for prime data records. 

Pc = 19-4-2/5 = 14 3/5 


Step 6 

The number of cylinders required to allocate prime space is 
determined by the number of prime data tracks required divided 
by the number of prime data tracks available on each cylinder. 
This area includes space for the prime data' records, track 
indexes, and cylinder overflow records. 

Number of 

cylinders = Prime data tracks required 

required Prime data tracks per cylinder 

C = T/Pc 

Example’- You need 401 tracks for prime data records. You can use 
14-3/5 tracks per cylinder. Therefore, 28 cylinders are required 
for your prime area and cylinder overflow areas. 

C = (401)/(14 3/5) = 27+ (round up to 28) 
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Step 7 


You will need space for a cylinder index as well as track 
indexes. There is a cylinder index entry for each track index 
(for each cylinder allocated for the data set). The size of each 
entry is the same as the size of the track index entries; 
therefore, the number of entries that will fit on a track is the 
same as the number of track index entries. Unused space on a 
cylinder index track is not shared. 

Number of tracks 

required for = Track inde x es+1 _ 

cylinder index Index entries per track 

Ci = (C+1)/It 

Example* You have 28 track indexes (from Step 6). Since 61 index 
entries fit on a track (from Step 3), you need 1 track for your 
cylinder index. The remaining space on the last track is unused. 

Ci = (28 + D/61 = 29/61 = 0.475 < 1 

Note that every time a cylinder index crosses a cylinder 
boundary, ISAM writes a dummy index entry that lets ISAM chain 
the index levels together. The addition of dummy entries can 
increase the number of tracks required for a given index level. 
To determine how many dummy entries will be required, divide the 
total number of tracks required by the number of tracks on a 
cylinder. If the remainder is 0, subtract 1 from the quotient. 

If the corrected quotient is not 0, calculate the number of 
tracks these dummy entries require. Also consider any additional 
cylinder boundaries crossed by the addition of these tracks and 
by any track indexes starting and stopping within a cylinder. 

Step 8 

If you have a data set large enough to require master indexes, 
you will want to calculate the space required according to the 
number of tracks for master indexes (NTM parameter) you 
specified in the DCB macro instruction or the DD statement. 

If the cylinder index exceeds the NTM specification, an entry is 
made in the master index for each track of the cylinder index. 

If the master index itself exceeds the NTM specification, a 
second-level master index is started. Up to three levels of 
master indexes are created if required. 

The space requirements for the master index are computed in the 
same way as those for the cylinder index. 

Number of tracks 

required for = Number of cylinder index tracks+1 

master indexes Index entries per track 

Ml = (Ci+1)/It when Ci>NTM 
M2 = (Ml+1)/It when Ml>NTM 
M3 = (M2 + 1)/It when M2>NTM 

Example* Assume that your cylinder index will require 22 tracks. 
Since large keys are used, only 10 entries will fit on a track. 
Assuming that NTM was specified as 2, 3 tracks will be required 
for a master index, and two levels of master index will be 
created. 

Ml = (22+l)/10 = 2.3 

Note that every time a master index crosses a cylinder boundary, 
ISAM writes a dummy index entry that lets ISAM chain the index 
levels together. The addition of dummy entries can increase the 
number of tracks required for a given index level. To determine 
how many dummy entries will be required, divide the total number 
of tracks required by the number of tracks on a cylinder. If the 
remainder is 0, subtract 1 from the quotient. If the corrected 
quotient is not 0, calculate the number of tracks these dummy 
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entries require. Also consider any additional cylinder 
boundaries crossed by the addition of these tracks and by any 
track indexes starting and stopping within a cylinder. 

Summary: Indexed Sequential Space Requirement Calculations 

1. How many blocks will fit on a track? 

Bt = 1 + ((Ct-Bn)/Bi) 

2. How many overflow records will fit on a track? 

Ot = 1 + ((Ct-Rn)/Ri) 

3. How many index entries will fit on a track? 

It = 1 + ((Ct-En)/Ei) 

4. How many track index tracks are needed per cylinder? 

Ic = (2(Tc-0c)+l)/(It+2) 

5. How many tracks on each cylinder can be used for prime data 
records? 

Pc = Tc-Oc-Ic 

6. How many cylinders are needed for the prime data area? 

C = T/Pc 

7. How many tracks are required for the cylinder index? 

Ci = (C+1)/It 

8. How many tracks are required for master indexes? 

M = (Ci+1)/It 


CONTROL AND DISPOSITION OF DATA SETS 


You specify two kinds of status and disposition information for 
the data sets you use for your processing by coding 
DISP=(status,disposition) in the disposition field of the DD 
statement. The first kind deals with the status of the data set 
when you begin processing and the relationship of the data set 
to other job steps in your job or other jobs. The second deals 
with what is to be done with the data set when you have 
completed processing. In the latter case, you can take advantage 
of the catalog of the operating system. 

A data set that is being used for input has a status of OLD. If 
it can be used by more than one job, the status should be 
specified as SHR. If you are going to add to the input data set, 
specify MOD. The system automatically positions the access 
mechanism after the last record when the data set is opened. A 
new output data set should be indicated as NEW. 

Having identified the status of the data set at the beginning of 
your job step, you should specify how you want it disposed of at 
the end of processing. If the disposition is to be unchanged, 
you need not specify anything. The status of an existing data 
set remains unchanged; a new data set is deleted. The requested 
disposition is performed at the end of the job step. A data set 
to be used in a later job can be kept (KEEP) until a subsequent 
request is made to delete it. If the data set is to be used by 
'more than one job step in the same job, you can specify that it 
is to be passed (PASS). 
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If you specify the CATLG disposition, the data set name is 
recorded in the catalog by the system and its volume is noted. 

An old data set can subsequently be removed from the catalog if 
you specify UNCATLG. 

If you wish, you can specify one disposition to be performed if 
the job step terminates normally, and a different disposition to 
be performed if the job step terminates abnormally. For example, 
you can specify DISP=(OLD,DELETE,KEEP) if you wish to delete a 
data set under normal conditions, but wish to keep it if 
processing is abnormally terminated. For normal termination, you 
can specify any disposition—PASS, KEEP, DELETE, CATLG, or 
UNCATLG; for abnormal termination, you can specify any 
disposition except PASS. 


ROUTING DATA THROUGH THE SYSTEM INPUT AND OUTPUT STREAMS 

The job entry subsystem is a system facility that provides 
spooling and scheduling of input and output data streams. 

Spooling includes two basic functions? 

• Input streams are read from the input device and stored on 
an intermediate storage device in a format convenient for 
later processing by the system and by the user’s program. 

• Output streams are similarly stored on an intermediate 
device until a convenient time for printing or punching. 

Scheduling provides the highest degree of system availability 
through the orderly use of system resources that are the objects 
of contention. 

With spooling, unit record devices are used at full rated speed 
if enough buffers are available, and they are used only for the 
time needed to read, print, or punch the data. Without spooling, 
the device is occupied for the entire time that a job is doing 
other processing. Also, because data is stored instead of being 
transmitted directly, output can be queued in any order and 
scheduled by class and by priority within each class. 

You enter data into the system input stream by preceding it with 
a DD * or DD DATA JCL statement. This is a 5YSIN data set. 

Your output data can be printed or punched from a SYSOUT data 
set, which is called the output stream. You code the SYSOUT 
keyword parameter in your DD statement and designate the 
appropriate output class. For example, SYS0UT r A requests output 
class A. The class-device relationship is established for each 
installation, and a list of devices assigned to each output 
class will enable you to select the appropriate one. Refer to 
QS/VS2 JCL for further information on SYSIN and SYSOUT 
parameters. 

SYSIN and SYSOUT must be BSAM or QSAM data sets and you open and 

close them in the same manner as any other data set processed on 

a unit record device (except when multiple DCBs are used to 
write to the same output class, the records are not 
interspersed.) The DCB exit routine will be entered in the usual 
manner if you specify it in an exit list. 

When you use QSAM with fixed-length blocked records or BSAM, the 
DCB block si 2 e parameter does not have to be a multiple of 
logical record length (LRECL) if the block size is specified 
through the SYSOUT DD statement. Under these conditions, if 
block size is greater than LRECL but not a multiple of LRECL, 

block size is reduced to the nearest lower multiple of LRECL 

when the data set is opened. This feature allows a cataloged 
procedure to specify blocking for SYSOUT data sets, even though 
your LRECL is not known to the system until execution. 
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Therefore, the SYSQUT DD statement of the go step of a 
compile-load~go procedure can specify block size without block 
size being a multiple of LRECL. For further information, refer 
to 0S/VS2 JCL . 

Because a SYSOUT data set is written on a direct-access device, 
you should omit the DEVD operand in the DCB macro instruction, 
or should code DEVD=DA. Because SYSIN and SYSOUT data sets are 
spooled on intermediate devices, you should also avoid using 
device dependent macro instructions (such as FEOV, CNTRL, PRTOV, 
BSP, or SETPRT) in processing these data sets. (See the 
sections, "Device Control" and "Device Independence.") With 3800 
Enhancements, you can use SETPRT when processing spooled data 
sets. For further information, refer to IBM 3800 Printing 
Subsystem Programmer’s Guide . 

The job entry subsystem controls all blocking and deblocking of 
your data to optimize system operation and ignores the number of 
channel programs (NCP) you specify. The block size (BLKSIZE) and 
number of buffers (BUFNO) specified in your program have no 
correlation with what is actually used by the job entry 
subsystem. Therefore, you can select the blocking factor that 
best fits your application program with no effect on the 
spooling efficiency' of the system. For QSAM applications, move 
mode is as efficient as locate mode. 

All record formats are allowed, except that spanned records 
(RECFM=VS or VB5) cannot be specified for SYSIN. A record format 
of FIXED is supplied if it is not specified for SYSIN. 

SYSIN support for undefined records is not compatible. The 
entire 80-byte image is treated as a record. Therefore, a read 
of less than 80-bytes results in the transfer of the entire 
80-byte image to the record area specified in the READ macro. 

The logical record length value (JFCLRECL field in the JFCB) is 
filled in with the logical record length value of the input data 
set. This value is increased by four if the record format is 
variable (RECFM=V or VB). The logical record length may be a 
size other than the size of the input device, if the SYSIN input 
stream is supplied by an internal reader. The job entry 
subsystem will supply a value in the JFCLRECL field of the JFCB 
if that field is found to be zero. 

The blocksize value (JFCBLKSI field in the JFCB) is filled in 
with the blocksize value of the input data set. This value is 
increased by four greater than the value calculated for the 
logical record value (that is, input data set logical record 
length +4) if the record format is variable (RECFM = V or VB). The 
job entry subsystem will supply a value in the JFCBLKSI field of 
the JFCB if that field is found to be zero. 

Your program is responsible for printing format, pagination, and 
header control. You can supply control characters for SYSOUT 
data sets in the normal manner by specifying ANSI or machine 
characters in the DCB. Standard controls are provided by default 
if they are not specified. The length of output records must not 
exceed the allowable maximum length for the ultimate device. 
Cards can be punched in EBCDIC mode only. 

Your SYNAD routine will be entered if an error occurs during 
data transmission to or from an intermediate storage device. 
Again, because the specific device is indeterminate, your SYNAD 
routine code should be device independent. 
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CONCATENATING SEQUENTIAL AND PARTITIONED DATA SETS 


Two or more sequential or partitioned data sets can be 
automatically retrieved by the system and processed successively 
as a single data set. This reading technique is known as 
concatenation . The maximum number of data sets that can be 
concatenated is governed by the limit of 255 extents (input data 
sets only). For example, 255 single extent data sets can be 
concatenated, but 16 data sets each with 16 extents cannot be 
concatenated. 

To save time when processing two consecutive data sets on a 
single volume, you specify LEAVE in your OPEN macro instruction. 
Concatenated data sets cannot be read backward. 

When data sets are concatenated, the system treats the group as 
a single data set and only one data extent block (DEB) is 
constructed. Thus, it is important to consider the 
characteristics of the individual data sets being concatenated. 
Data sets with like characteristics are those that may be 
processed correctly using the same data control block (DCB), 
input/output block (IOB), and channel program. Any exception 
makes them unlike. Concatenated partitioned data sets are always 
treated as like and use the attributes of the first data set 
only. You must inform the system by modifying the DCBOFLGS field 
of the DCB if unlike data sets are concatenated (this is not 
required for spool data sets, because EOV automatically treates 
them as unlike data sets). The indication must be made before 
the end of the current data set is reached. You must set bit 4 
to 1 by using the instruction 01 DCBOFLGS,X T 08' as described in 
"Modifying the Data Control Block.” If bit 4 of the DCBOFLGS 
field is 1, end-of-volume processing for each data set will 
issue a CLOSE for the data set just read and an OPEN for the 
next concatenated data set. This opening and closing procedure 
updates the fields in the DCB and, if necessary, builds a new 
IOB and a new channel program. If the buffer pool was obtained 
automatically by the open routine, the procedure also frees the 
buffer pool and obtains a new one for the next concatenated data 
set. The procedure does not issue a FREEP00L for the last 
concatenated data set. Unless you have some way of determining 
the characteristics of the next data set before it is opened, 
you should not reset the DCBOFLGS field to indicate like 
characteristics during processing. When you concatenate data 
sets with unlike attributes, no EOV exits are taken. 

When unlike data sets have been concatenated, you should not 
issue multiple input requests, that is, a series of READ or GET 
macro instructions, in your program. If you do, you will have to 
arrange some way to determine which requests have been completed 
and which must be reissued. In any case, the GET or READ macro 
instruction that detected the end of data set will have to be 
reissued. Figure 65 illustrates a possible routine for 
determining when a GET or READ must be reissued. This 
restriction does not apply to like data sets since no open or 
close operation is necessary between data sets. 
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•Returns are to control 
program address in register 14 


Figure 65. Reissuing a READ for Unlike Concatenated Data Sets 


When the change from one data set to another is made, label 
exits are taken as required; automatic volume switching is also 
performed for multiple-volume data sets unless they are 
partitioned. Your end-of-data-set CEODAD) routine is not entered 
until the last data set has been processed, except that for 
partitioned data sets, your EODAD routine receives control at 
the end of each member. At that time, you can process the next 
member or close the data set. 

You process a concatenation of partitioned data sets the same 
way you process a single partitioned data set with one 
exception. You must use the FIND macro instruction to begin 
processing a member; you cannot use the POINT (or NOTE) macro 
instruction until after the FIND macro instruction has been 
issued. Figure 49 on page 101 shows how to process a single 
partitioned data set using FIND. If two members of different 
data sets in the concatenation have the same name, the FIND 
macro instruction determines the address of the first one in the 
concatenation. You would not be able to process the second one 
in the concatenation. The BLDL macro instruction provides the 
concatenation number of the data set to which the member belongs 
in the K field of the build list. See the section 
"BLDL—Construct a Directory Entry List" in Part 2 of this book. 

If issuing an RDJFCB macro, see the RDJFCB macro instruction in 
the P5/V52 System Programming Library- Data Management . 
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Rotational Position Sensing Considerations 

Direct-access storage devices with the rotational position 
sensing (RPS) feature (for example, the 3330) usually employ 
channel programs that are not compatible with direct-access 
storage devices that lack the RPS feature. Therefore, if you 
concatenate otherwise "like" data sets residing on devices both 
with and without the RPS feature, standard (non-RPS) channel 
programs will be used, with a resultant loss of the I/O overlap 
efficiency of rotational position sensing. Concatenated 
partitioned data sets are always treated as "like" data sets, 
regardless of how the DCBOFLGS field is set in the DCB. Data 
sets with undefined length records and track overflow (RECFM = UT 
specified in the DCB) are not processed with the RPS feature. 

When you concatenate sequential data sets with "unlike" 
attributes, and the "unlike" attribute bit in the DCB is set 
prior to open, and no non-RPS direct-access devices are included 
in the concatenation, RPS channel programs are generated. If you 
include both RPS and non-RPS direct-access devices in the 
concatenation, non-RPS channel programs are generated in all 
cases. 

Further discussion and examples of concatenated data sets are 
contained in QS/VS2 JCL . 


CATALOGING DATA SETS 

The MVS operating system has a catalog structure consisting of a 
VSAM master catalog, VSAM user catalogs, and, optionally, 
control volumes (CVOIS). Figure 66 shows the MVS catalog 
structure. 


Master Catalog 



1 111111 is the volume serial of the control volume. 
Figure 66. MVS Catalog Structure 


There is one master catalog on each system. It is required and 
contains entries for system data sets. It is also the VSAM 
master catalog and does not have to be on the system residence 
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volume. The master catalog contains a pointer to each user 
catalog. Both VSAM and non-VSAM data sets can be cataloged in a 
user catalog. 

Non-VSAM data sets can be cataloged on control volumes (SYSCTLG 
data sets). The master catalog contains a pointer to each 
control volume. Data sets can be cataloged, uncataloged, or 
recataloged. For more information on using CVOLs in an MVS 
system, see QS/V52 MVS CVOL Processor . If a data set is not 
cataloged in the master catalog, the first name of a qualified 
data set name indicates the user catalog or control volume in 
which it is cataloged. A user catalog can also be connected to 
the VS2 system as a job catalog or a step catalog. 

Permanent Mass Storage System (MSS) data sets should be 
cataloged to allow efficient use of the Mass Storage Volume 
Control (MSVC) functions. For information on MSVC, see OS/VS 
Mass Storage System (MSS) Services- General Information . 


Entering a Data Set Name in the Catalog 

The data set name of a non-VSAM data set can be entered in a 
master or user catalog through (1) job control language (DISP 
parameter), (2) Access Method Services (DEFINE command), or (3) 
catalog management macro instructions (CATALOG and CAMLST). A 
non-VSAM data set name can be entered in a control volume 
through JCL or the catalog management macros. VSAM data sets can 
only be cataloged by using Access Method Services. 

Access Method Services is also used to establish aliases for 
data set names and to connect user catalogs and control volumes 
to the master catalog. See 0S/VS2 Access Method Servic es for 
information on how to use the Access Method Services commands. 
See QS/VS2 System Programming Library? Data Management for 
information on how to use the catalog management macro 
instructions. 


GENERATION DATA GROUPS 


A generation data group is a group of related cataloged data 
sets. The manner in which these data sets are cataloged is what 
makes them a generation data group. Within a generation data 
group, the generations can have like or unlike DCB attributes 
and data set organizations. If the attributes and organizations 
of all generations in a group are identical, the generations can 
be retrieved together as a single data set. Each data set within 
a generation data group is called a generation data set. 
Generation data sets are sometimes called generations . 


There are advantages to grouping related data sets. Because the 
catalog management routines can refer to the information in a 
special index—called a generation index —in the catalog* 

• All of the data sets in the group can be referred to by a 
common name. 

• The operating system is able to keep the generations in 
chronological order. 


Outdated or obsolete generations can be automatically 
deleted by the operating system. 


The management of a generation data group depends upon the fact 

that generation data sets have sequentially ordered 

names—absolute and relative names—that represent their age. 

The absolute generation name is the representation used by the 
catalog management routines in the catalog. Older data sets have 
smaller absolute numbers. The relative name is a signed integer 
used to refer to the latest (0), next to the latest (—1), etc. 
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generation. The relative number can also be used to catalog a 
new generation (+1). 

In MVS, a generation data group base is created in a VSAM 
catalog before the generation data sets are cataloged. A 
generation data group is represented in the VSAM catalog by a 
generation data group base entry. The Access Method Services' 
DEFINE command is used to create the generation data group base. 
See 0S/VS2 Access Method Services for information on how to 
define and/or catalog generation data sets. 


ABSOLUTE GENERATION AND VERSION NUMBERS 

An absolute generation and version number is used to identify a 
specific generation of a generation data group. The generation 
and version numbers are in the form GxxxxVyy, where xxxx i 5 an 
unsigned foui—digit decimal generation number ( 0001-9999) and yy 
is an unsigned two-digit decimal version number (00-99). For 
example 1 

• A.B^C.G0001V00 is generation data set one, version zero, in 
generation data group A.B.C. 

• A.B.C.G0009V01 is generation data set nine, version one, in 
generation data group A.B.C. 

The number of generations and versions is limited by the number 
of digits in the absolute generation name, that is, 9999 for 
generations and 100 for versions. 

The generation number is automatically maintained by the system. 
The number of generations kept depends on the size of the 
generation index. For example, if the size of the generation 
index allows ten entries, the ten latest generations may be 
maintained in the generation data group. 

The version number allows you to perform normal data set 
operations without disrupting the management of the generation 
data group. For example, if you want to update the second 
generation in a three-generation group, replace generation two, 
version zero, with generation two, version one. Only one version 
is kept per generation. 

A generation can be cataloged using either absolute or relative 
numbers. When a generation is cataloged, a generation and 
version number is placed as a low level entry in the generation 
data group. In order to catalog a version number other than V00, 
you must use an absolute generation and version number. 

A new version of a specific generation can be cataloged 
automatically by specifying the old generation number along with 
a new version number. For example, if generation A.B.C.G0005V00 
is cataloged in the index and you now create and catalog 
A.B.C.G0005V01, the new entry is cataloged in the index location 
previously occupied by A . B.C.GO 005V00. This process removes the 
old entry from the catalog but does not scratch the old version. 
To scratch the old version and make its space available for 
reallocation, a DD card, describing the data set to be deleted, 
with DISP=(OLD,DELETE) should be included at the time the data 
set is to be replaced by the new version. 


RELATIVE GENERATION NUMBER 

As an alternative to using absolute generation and version 
numbers when cataloging or referring to a generation, you can 
use a relative generation number. To specify a relative number, 
use the generation data group name followed by a negative 
integer, a positive integer, or a zero, enclosed in parentheses. 
For example, A.B.C(-l). A.B.C(+1), or A.B.C(O). 

The value of the specified integer tells the operating system 
what generation number to assign to a new generation, or it 
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tells the system the location (in the generation index) of an 
entry representing a previously cataloged generation. 

When you use a relative generation number to catalog a 
generation, the operating system assigns an absolute generation 
number and a version number of V00 to represent that generation. 
The absolute generation number assigned depends on the number 
last assigned and the value of the relative generation number 
that you are now specifying. For example if, in a previous job 
generation, A . B.C.GO 005V00 was the last generation cataloged, 
and you specify A.B.CC+l), the generation now cataloged is 
assigned the number G0006VOO. Though any positive relative 
generation number can be used, a number greater than 1 may cause 
absolute generation numbers to be skipped. For example, if you 
have a single-step job, and the generation being cataloged is a 
+ 2, one generation number is skipped. However, in a 
multiple-step job, one step may have a +1 and a second step a 
+2, and no numbers are skipped in this case. 

Note: If you do not specify a volume in the JCL for a new 
generation data set, and the data set is not opened, that data 
set is not cataloged. 


Programming Considerations for Multiple-Step Jobs 

One of the reasons for using generation data groups is to allow 
the system to maintain a given number of related cataloged data 
sets. If you attempt to delete or uncatalog any but the oldest 
of the data sets of a generation data group in a multiple-step 
job, catalog management can lose orientation within the data 
group. This can cause the deletion, uncataloging, or retrieval 
of the wrong data set when referring to a specified generation. 
The rule is, if you delete a generation data set in a 
multiple-step job, do not refer to any older generation in 
subsequent job steps. 

Also, it is recommended that in a multiple-step job, you catalog 
or uncatalog data sets using JCL instead of IEHPROGM or a user 
program. Since ALLOCATION/UNALLOCATION monitors data sets during 
job execution and is not aware of the functions performed by 
these programs, data set orientation may be lost or conflicting 
functions may be performed in subsequent job steps. 

When you use a relative generation number to refer to a 
generation that was cataloged in a previous job, the relative 
number has the following meaning: 

• A.B.C(O) refers to the latest existing cataloged entry. 

• A.B.C(-l) refers to the next-to-the-latest entry, etc. 

When cataloging is requested via JCL, all actual cataloging 
occurs at step termination, but the relative generation number 
remains the same throughout the job. Because this is so: 

• A relative number used in the JCL refers to the same 
generation throughout a job. 

• A job step that terminates abnormally may be deferred for a 
later step restart. If the step cataloged a generation data 
set via JCL, you must change all relative generation numbers 
in the succeeding steps via JCL before resubmitting the job. 

For example, if the succeeding steps contained the relative 
generation numbers 5 

• A.B.CC+l), which refers to the entry cataloged in the 
terminated job step. 

• A.B.C(O), which refers to the next to the latest entry. 

• A.B.C(-l), which refers to the latest entry, prior to 
A.B.CCO). 
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You must change them as follows before the step can be 
restarted A.B.C(O)/ A.B.C(-l)/ A.B.C(-2)> etc. 


BUILDING A GENERATION INDEX IN A CVOL 

A generation data group is managed via the information found in 
a generation index. (Note that an alias name cannot be assigned 
to the highest level of a generation index.) The BLDG function 
builds the index. The BLDG function also indicates how older or 
obsolete generations are to be handled when the index is full. 
For example^ when the index is full/ you may wish to empty it» 
scratch existing generations/ and begin cataloging a new series 
of generations. 

After the index is built/ a generation can be cataloged by its 
generation data group name and either an absolute generation and 
version number or a relative generation number. 

Examples on how to build a generation-data-group index are found 
in OS/VS2 MVS Utilities. 







CREATING A NEW GENERATION 

To create a new generation data set you must first allocate 
space for the generation/ then catalog the generation. 


Allocating a Generation 

To take full advantage of the facilities of the system/ the 
allocation can be patterned after a previously allocated 
generation in the same group. This is accomplished by the 
specification of DCB attributes for the new generation as 
described below. 

If you are using absolute generation and version numbers/ DCB 
attributes for a generation can be supplied directly in the DCB 
parameter of the DD statement defining the generation to be 
created and cataloged. 

If you are using relative generation numbers to‘catalog 
generations/ DCB attributes can be supplied either 1 (1) by 
creating a model DSCB on the volume on which the index resides 
(the volume containing the catalog) or (2) by referring to a 
cataloged data set for the use of its attributes. Attributes can 
be supplied before you catalog a generation/ when you catalog 
it/ or at both times/ as follows! 

1. Create a model DSCB on the volume on which your index 

resides. You can provide initial DCB attributes when you 
create your model; however/ you need not provide any 
attributes at this time. Since only the attributes in the 
data set label are used/ the model data set should be 
allocated with SPACE=(TRK/0) to conserve direct-access 
space. Initial or overriding attributes can be supplied when 
you create and catalog a generation. 2 To create a model 
DSCB/ include the following DD statement in the job step 
that builds the index or in any other job step that precedes 
the step in which you create and catalog your generation. 

//name DD DSNAME=datagrpname/DISP=(/KEEP)zSPACE=(TRK/(0))/ 

// UNIT=yyyy / VOLl)ME = SER = xxxxxx/ 

// DCB=(applicable subparameters) 




* 


■a 


Only one model DSCB is necessary for any number of generations. If you plan 
to use only one model/ do not supply DCB attributes when you create the 
model. When you subsequently create and catalog a generation/ include 
necessary DCB attributes in the DD statement referring to the generation. 

In this manner/ any number of generation data groups can refer to the same 
model. Note that the catalog and model data set label are always located on 
a direct-access volume/ even for a magnetic tape generation data group. 
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The DSNAME is the common name by which each generation is 
identified; xxxxxx is the serial number of the volume 
containing the catalog. If no DCB subparatneters are desired 
initially^ you need not code the DCB parameter. 

2. You do not need to create a model DSCB if you can refer to a 
cataloged data set whose attributes are identical to those 
you desire or to an existing model DSCB for which you can 
supply overriding attributes. A cataloged data set referred 
to in this manner must reside on the same volume os your 
index. To refer to a cataloged data set for the use of its 
attributes, specify DCB=Cdsname) on the DD statement that 
creates and catalogs your generation. To refer to an 
existing model, specify DCB^Cmodeldscbname, your attributes) 
on the DD statement that creates and catalogs your 
generation. 


Passing a Generation 

A new generation may be passed when created. That generation may 
then be cataloged in a succeeding job step or deleted at the end 
of the job as in normal disposition processing when DISP=(,PA5S) 
is specified on the DD statement. 

However, once a generation has been created with DISP=(NEW,PASS) 
specified on the DD statement, another new generation for that 
data group must not be cataloged until the passed version has 
been deleted or cataloged. To do so would cause the wrong 
generation to be used when referencing the passed generation 
data set. If that data set was later cataloged, a bad generation 
would be cataloged and a good one lost. 


For example, if A.B.CC+l) was created with DISP=(NEW,PASS) 
specified on the DD statement, then A.B.C.C+2) must not be 
created with DISP=(NEW,CATLG) until A.B.CC+l) has been cataloged 
or deleted. 


By using the proper JCL, the advantages to this support are: 

• JCL will not have to be changed in order to rerun the job. 

• The lowest generation version will not be deleted from the 
index until a valid version is cataloged. 


Creating an ISAM Data Set as Part of a Generation Data Group 

To create an indexed-sequential data set as part of a generation 
data group, you must: (1) create the indexed-sequentia 1 data set 
separately from the generation group and (2) use IEHPROGM to put 
the indexed-sequential data set into the generation group. 

Use the RENAME function to rename the data set. Then use the 
CATLG function to catalog the data set. For instance, if MASTER 
is the name of the generation data group, and GggggVvv is the 
absolute generation name, you would code the following: 

RENAME DSNAME=ISAM,V0L=2314=SCRTCH,NEWNAME=MASTER.GggggVvv 
CATLG DSNAME=MASTER.GggggVvv,VOL=2314=SCRTCH 


RETRIEVING A GENERATION 

A generation may be retrieved through the use of job control 
language procedures. Any operation that can be applied to a 
non-generation data set can be applied to a generation. For 
example, a generation can be updated and reentered in the 
catalog, or it can be copied, printed, punched, or used in the 
creation of new generation or non-generation data sets. 

You can retrieve a generation by using either relative 
generation numbers or absolute generation and version numbers. 
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Because two or more jobs can compete for the same resource, 
generation data groups should be updated with care, as follows 1 


• No two jobs running concurrently should refer to the same 
generation data group. As a partial safeguard against this 
situation, use absolute generation and version numbers when 
cataloging or retrieving a generation in a multiprogramming 
environment. If you use relative numbers, a job running 
concurrently may update the generation data group index, 
perhaps cataloging a new generation which you will then 
retrieve in place of the one you wanted. 


Even when using absolute generation and version numbers, a 
job running concurrently might catalog a new version of a 
generation or perhaps delete the generation you wished to 
retrieve. For this reason, some degree of control should be 
maintained over the execution of job steps referring to 
generation data groups. 


CONTROLLING CONFIDENTIAL DATA 


PASSWORD PROTECTION FOR NON-VSAM DATA SETS 

Password protection as described here applies to non-VSAM data 
sets only. For information on password protection for VSAM data 
sets, see 0S/VS2 Access Method Services . 

In addition to the usual label protection that prevents opening 
of a data set without the correct data set name, the operating 
system provides data set security options that prevent 
unauthorized access to confidential data. Two levels of 
protection options are available. You specify these options in 
the LABEL field of a DD statement with the parameter PASSWORD or. 
NOPWREAD. 

• Password protection (specified by the PASSWORD parameter) 
makes a data set unavailable for all types of processing 
until a correct password is entered by the system operator, 
or for a TSO job on MVS, the ISO user. 

• No-password-read protection (specified by the NOPWREAD 
parameter) makes a data set available for input without a 
password, but requires that the password be entered for 
output or delete operations. 

If an incorrect password is entered twice, the job is terminated 
by the system if it is being requested by the open or EOV 
routine. For a scratch or rename request, a return code is 
given. 

You can request password protection when you create the data set 
by using the LABEL field of the DD statement in your JCL. The 
system sets the data set security byte either in the standard 
header label 1 as shown in OS/VS Tape Labels or in the 
identifier data set control block (DSCB) as shown in QS/VS2 
System Programming Library? Debugging Handbook . Once you have 
requested security protection for magnetic tapes, you cannot 
remove it with JCL unless you recreate the data set and scratch 
the protected data set. 

In addition to requesting password protection in your JCL, you 
must enter at least one record for each protected data set in a 
data set named PASSWORD that must be created on the 
system-residence volume. You should also request password 
protection for the PASSWORD data set itself to prevent both 
reading and writing without knowledge of the password. 

For a data set on a direct-access device, you can place the data 
set under protection at the same time that you enter its 
password in the PASSWORD data set. You can use the PROTECT macro 
instruction or the IEHPROGM utility program to add, change, or 
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delete an entry in the PASSWORD data set; with either of these 
methods, the system updates the DSCB of the data set to reflect 
its protected status. This provision eliminates the need for you 
to use JCL whenever you add, change, or remove security 
protection for a data set on a direct-access device. QS/VS2 
System Programming Library- Data Management describes how to 
maintain the PASSWORD data set, including the PROTECT macro 
instruction; D5/VS2 MVS Utilities describes the IEHPR0GM utility 
program. 


RACF PROTECTION FOR NON-VSAM DASD DATA SETS AND TAPE VOLUMES 


RACF (Resource Access Control Facility) protection as described 
here applies to non-VSAM data sets and tape volumes. For 
information on RACF protection for VSAM data sets, see 0S/V52 
MVS Resource Access Control Facility (RACF)- General 
Information Manual . 

RACF i£ a program product that provides for access control by 
identifying and verifying users and authorizing access to DASD 
data sets, and tape volumes with either standard or ANSI labels, 
which are defined to RACF. 

You may define a data set to RACF automatically or explicitly. 
The automatic definition occurs when space is allocated for the 
data set, if the user has the automatic data set protection 
attribute or if PROTECT=YES is coded on the DD statement. The 
explicit definition of a data set to RACF is by use of the RACF 
command language. 

A tape volume is defined to RACF explicitly by use of the RACF 
command language or automatically. This automatic definition 
occurs when the first data set on the first (or only) private 
volume is opened for OUTPUT or OUTIN and PROTECT=YES has been 
coded in the DD statement. RACF protection of tape data sets is 
provided on a volume basis and not on a data set basis. All data 
sets on a tape volume are RACF-protected if the volume is 
RACF-protected. 

There are five levels of access authority which you may have to 
a RACF-defined DASD data set or tape volume. 

ALTER 

You have total control over the data set. If you define the 
DASD data set or tape volume to RACF, you have ALTER access 
authority. With ALTER authority, you can read and write the 
data set or tape volume, rename the data set, and scratch 
the data set, and you may authorize other users access to 
the tape volume or data set. 

CONTROL 

For non-VSAM data sets, CONTROL authority is equivalent to 
UPDATE authority. 

UPDATE 

You are authorized to open the data set or tape volume for 
OUTPUT and all other open options. 

READ 

You are authorized to open the data set or tape volume for 
INPUT only. 

NONE 

You are not authorized to open the data set or tape volume. 

If a DASD data set is both defined to RACF and 
password-protected, access to the data set is authorized only 
through RACF authorization checking. If a tape volume is defined 
to RACF and the data set(s) on the tape volume is 
password-protected, access to any of the data sets is authorized 
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only through RACF authorisation checking of the volume. Data set 
password protection is bypassed. 

To protect multivolume nonVSAM DASD and tape data sets, you must 
define each volume of the data set to RACF as part-of the same 
volume set. When a RACF-protected data set is opened for output 
and extended to a new volume, the new volume will be 
automatically defined to RACF as part of the same volume set. 
When a multivolume physical sequentially organised data set is 
opened for output and the first volume opened is RACF-protected, 
each subsequent volume must either be RACF-protected as part of 
the same volume set, or the data set must not yet exist on the 
volume. When a multi volume tape data set is opened for output 
and the first volume opened is RACF-protected, each subsequent 
volume must be either RACF-protected as part of the same volume 
set, or the tape volume must not yet be defined to RACF. If the 
first volume opened is not RACF-protected, no subsequent volume 
may be RACF-protected. If a multi volume data set is opened for 
input (or a nonphysical sequentially organized data set is 
opened for output), no such consistency check is performed when 
subsequent volumes are accessed. 


154 0S/VS2 Data Management Services Guide 




APPENDIX A. DIRECT-ACCESS LABELS 


Only standard label formats are used on direct-access volumes. 
Volume* data set, and optional user labels are used (see 
Figure 67). In the case of direct-access volumes, the data set 
label is the data set control block (DSCB). 



Figure 67. Direct-Access Labeling 


VOLUME-LABEL GROUP 


The volume-label group immediately follows the first two initial 
program loading (IPL) records on track 0 of cylinder 0 of the 
volume. It consists of the initial volume label at record 3 plus 
a maximum of seven additional volume labels. The initial volume 
label identifies a volume and its owner, and is used to verify 
that the correct volume is mounted. It can also be used to 
prevent use of the volume by unauthorized programs. The 
additional labels can be processed by an installation routine 
that is incorporated into the system. 

The format of the direct-access volume label group is shown in 
Figure 68 on page 156. 


Appendix A. Direct-Access Labels 155 







(Up to 7 Additional Volume Labels) 



Figure 68. Initial Volume Label 


V , 






INITIAL VOLUME LABEL FORHAT 

The 80-byte initial volume label is preceded by a foui—byte key 
containing V0L1. 

VOLUME LABEL IDENTIFIER (VOL): Field 1 identifies a volume 
label. 

VOLUME LABEL NUMBER (1): Field 2 identifies the relative 
position of the volume label in a volume label group. It must be 
written as X'C'l'. 

The operating system identifies an initial volume label when* in 
reading the initial record, it finds that the first 4 characters 
of the record are V0L1. 

X 


r 


VOLUME SERIAL NUMBER 2 Field 3 contains a unique identification 
code assigned when the volume enters the system. You can place 
the code on the external surface of the volume for visual 
identification. The code is normally numeric (000001-999999), 
but may be any 1 to 6 alphameric or national (#, $, 3) 
characters, or a hyphen (X’60 f ). If this field is less than 6 
characters, it is padded on the right with blanks. 

VOLUME SECURITY 2 Field 4 is reserved for use by installations 
that wish to provide security for volumes. Make this field a 
C’0’ unless you have your own security processing routines. 

VTOC POINTER’* Field 5 of direct-access volume label 1 contains 
the address of the VTOC in the form of CCHHR. 
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RESERVED 1 Field 6 is reserved for future developmental purposes. 
Leave it blank. 

OWNER NAME AND ADDRESS CODE: Field 7 contains a unique 
identification of the owner of the volume. 

All the bytes in Field 8 are left blank. 


DATA SET CONTROL BLOCK (DSCB) 


The system automatically constructs a DSCB when space is 
requested for a data set on a direct-access volume. Each data 
set on a direct-access volume has one or more DSCBs to describe 
its characteristics. The DSCB appears in the VTOC and contains 
operating-system data, device-dependent information, and data 
set characteristics, in addition to space allocation and other 
control information. There are seven kinds of DSCBs,. each with a 
different purpose and a different format number. For an 
explanation of the seven kinds of DSCBs, see 0S/VS2 System 
Programming Library: Debugging Handbook. 


USER LABEL GROUPS 


User header and trailer label 
sets of physically sequential 
in each group have the format 


groups can be included with data 
or direct organisation. The labels 
shown in Figure 69. 


Fi eld 



80-Byte Physical Record (Maximum of 8) 

Label Identifier (UHL if Header, UTL if Trailer) 
Label Number (1 - 8) 


Usei—Specified 


Figure 69. User Header and Trailer Labels 


Each group can include up to eight labels, but the space 
required for both groups must not be more than 1 track on a 
direct-access device. The current minimum track sise allows a 
maximum of eight labels, including both header and trailer 
labels. Consequently, a program becomes device-dependent (among 
direct-access devices) when it creates more than eight labels. 

If user labels are specified in the DD statement (LABEL^SUL), an 
additional track is normally allocated when the data set is 
created. No additional track is allocated when specific tracks 
are requested (SPACE=( ABSTR, ...,)), or when tracks allocated to 
another data set are requested (SUBALL0C=...). In either case, 
labels are written on the first track that is allocated. 
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User Header Label Group'* The operating system writes these 
labels as directed by the processing program recording the data 
set. The first 4 characters of the user header label must be 
UHL1,...» UHL8; you can specify the remaining 76 characters. 
When the data set is read, the operating system makes the user 
header labels available to the problem program for processing. 

User Trailer Label Group: These labels are recorded (and 
processed) as explained in the preceding text for user header 
labels, except that the first 4 characters must be UTL1,...., 
UTL8. 


USER HEADER AND TRAILER LABEL FORMAT 

LABEL IDENTIFIER'* Field 1 indicates the kind of user header 
label. UHL indicates a user header label; UTL indicates a user 
trailer label. 

LABEL NUMBER: Field 2 identifies the relative position (1-8) of 
the label within the user label group. 

USER-SPECIFIED: Field 3 (76 bytes). 
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APPENDIX B. CONTROL CHARACTERS 


As an optional feature* each logical record* in any record 
format, may include a control character. This control character 
is recognized and processed if a data set is being written to a 
printer or punch. 

For format-F and format-U records, this character is the first 
byte of the logical record. 

For format-V records* it must be the fifth byte of the logical 
record, immediately following the record descriptor word. 

Two options are available. If either option is specified in the 
DCB* the character must appear in every record and other line 
spacing or stacker selection options also specified in the DCB 
are ignored. 


MACHINE CODE 


You can specify in the DCB that the machine code control 
character has been placed in each logical record. If the record 
is to be written* the appropriate byte must contain the command 
code bit configuration specifying both the write and the desired 
carriage or stacker select operation. 

The machine code control characters for a printer are as 
follows* 
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Print and Then Act 


Code in Hexadecimal 


01 


09 



I 

Action 

Print i 

only (no space) 

Space 

1 line 


Spai 

ce 

2 lines 


Spa 

ce 

3 lines 


Skip 

to 

channel 

1 

Sk i p 

to 

channel 

2 

Ski p 

to 

channel 

3 

Skip 

to 

channel 

4 

Ski p 

to 

channel 

5 

Ski p 

to 

channel 

6 

Skip 

to 

channel 

7 

Skip 

to 

channel 

8 

Skip 

to 

channel 

9 

Skip 

to 

channel 

10 

Skip 

to 

channel 

11 

Ski p 

to 

channel 

12 


Act ImmediatelyCNo Printing) 


Code in Hexadecimal 



The machine code control characters for a card read punch device 
are as follows: 


Code in Hexadecimal 

Action 

01 

Select stacker 1 

41 

Select stacker 2 

81 

Select stacker 3 


Other command codes for specific devices are contained in 
publications describing the control units and devices. 
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EXTENDED AMERICAN NATIONAL STANDARDS INSTITUTE CODE 


In place of machine code, you can specify control characters 
defined by the American National Standards Institute, Inc. 
(ANSI). Whenever IBM publications refer to ANSI code, they are 
as follows^ 

Code Action Before Printing a Line 

b Space one line (blank code) 

0 Space two lines 

Space three lines 
+ Suppress space 


1 

Ski 

P 

to 

channel 

1 

2 

Ski 

P 

to 

channel 

2 

3 

Ski 

P 

to 

channel 

3 

4 

Ski 

P 

to 

channel 

4 

5 

Ski 

P 

to 

channel 

5 

6 

Ski 

P 

to 

channel 

6 

7 

Ski 

P 

to 

channel 

7 

8 

Ski 

P 

to 

channel 

8 

9 

Ski 

P 

to 

channel 

9 

A 

Ski 

P 

to 

channel 

10 

B 

Ski 

P 

to 

channel 

11 

C 

Ski 

P 

to 

channel 

12 


Code Action After Punching a Card 

V Select punch pocket 1 

W Select punch pocket 2 

These control characters include those defined by ANSI FORTRAN. 
If any other character is specified, it is interpreted as ’b' or 
V, depending on whether it is for a printer or a punch; no error 
indication is returned. 
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GLOSSARY OF ACRONYMS AND ABBREVIATIONS 


The following terms are defined as 
they ore used in this hook. If you do 
not find the term you are looking for> 
refer to the index or to the IBM Data 
Processing Glossary , GC20-1699. 

A! ANSI control code (value of RECFM) 

ABE: abnormal end (value of EROPT) 

ABEND: abnormal end (macro 
instruction) 

ABSTR: absolute track (value of SPACE) 

ACC: accept erroneous block (value of 
EROPT) 

AFF: affinity (channel separation 
parameter of DD statement or unit 
affinity value of UNIT) 

AL: American National Standard Labels 

ANSI: American National Standards 
Institute 

ASCII: American National Standard Code 
for Information Interchange 

AUL: American National Standard User 
labels (value of LABEL) 

B: blocked records (value of RECFM) 

BCDIC: binary coded decimal 
interchange code 

BDAH: basic direct access method 

BDW: block descriptor word 

BFALN: buffer alignment (operand of 
DCB) 


BFTEK: buffer technique (operand of 
DCB) 

BISAM: basic indexed sequential access 
method 

BLDL: build list (macro instruction) 
BLKSIZE: blocksize (operand of DCB) 
BPAM: basic partitioned access method 
BPi: bits per inch 

BSAFi: basic sequential access method 

BSM: backspace past tapetnark and 
forward space over tapemark (operand 
of CNTRL) 

BSP: backspace one block (macro 
instruction) 


BSR: backspace over a specified number 
of blocks (records) (operand of CNTRL) 

BUFCB: buffer pool control block 
(operand of DCB) 

BUFL: buffer length (operand of DCB) 

BUFNO: buffer number (operand of DCB) 

BUFOFF: Buffer offset (length of ASCII 
block prefix by which the buffer is 
offset; operand of DCB) 

CCW: channel command word 

CONTIG: contiguous space allocation 
(value of SPACE) 

CNTRL: control (macro instruction) 

CPI): central processing unit 

CSU: channel status word 

CYLOFL: number of tracks for cylinder 
overflow records (operand of DCB) 

D: format-D (ASCII variable-length) 
records (value of RECFM) 

DA: direct-access (value of DEVD or 
DSORG) 

DAU: direct-access unmovable data set 
(value of DSORG) 

DCB: data control block (control block 
name or macro instruction) 

DCED: data control block dummy section 
macro instruction 

DD: data definition 

DEB: data extent block 

DECB: data event control block 

DEN: magnetic tape density (operand of 
DCB) 


DEVD: device-dependent (operand of 
DCB) 

DISP: data set disposition (parameter 
of DD statement) 

DSCB: data set control block 

DSORG: data set organization (operand 
of DCB) 

EBCDIC: extended binary coded decimal 
interchange code 

EODAD: end-of-data set exit routine 
address (operand of DCB) 
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EOF! end-of-file 
EOVi end-of-volume 

EROPT! error options (operand of DCB) 

ESETLi end sequential retrieval (QISAM 
macro instruction) 

EXCPi execute channel program (macro 
instruction) 

EXLST! exit list (operand of DCB) 

F! fixed-length records (value of 
RECFM) 

FBI fixed-length, blocked records 
(value of RECFM) 

FBSi fixed-length, blocked, standard 
records (value of RECFM) 

FBTI fixed-length, blocked records 
with track overflow option (value of 
RECFM) 

FCBi forms control buffer 

FEOV: force end-of-volume (macro 
instruction) 

FSi fixed-length, standard records 
(value of RECFM) 

FSMJ forward space past tapemark and 
backspace over tapemark (operand of 
CNTRL) 

FSRI forward space over a specified 
number of blocks (records) (operand of 
CNTRL) 

GCRi group coded recording 

GLi GET macro, locate mode (value of 
MACRF) 


GMi GET macro, move mode (value of 
MACRF) 

HA! home address 
I/O! input/output 

INOUT! input then output (operand of 
OPEN) 

IOBi input/output block 

IPL! initial program load 

IRGi interrecord gap 

IS! indexed sequential (value of 
DSORG) 

ISAM! indexed sequential access method 

ISU! indexed sequential unmovable 
(value of DSORG) 

JCL! job control language 


JFCBi job file control block 

JFCBE! job file control block 
extension for 3800 printer 

KEYLENi key length (operand of DCB) 

LPAi link pack area 

LPALIB! link pack area library 

LRECL! logical record length (operand 
of DCB) 

M! machine control code (value of 
RECFM) 

MACRF! macro instruction form (operand 
of DCB) 

MOD! modify data set (value of DISP) 

MSHI! main storage for highest-level 
index (operand of DCB) 

MSS! Mass Storage System 

MSVCl Mass Storage Volume Control 

MSWAi main storage for work area 
(operand of DCB) 

NCPi number of channel programs 
(operand of DCB) 

NOPWREADi no password to read a data 
set (value of LABEL) 

NRZI! non-return-to-zero-inverted 
(tape recording mode.) 

NSLi nonstandard label (value of 
LABEL) 

NTM! number of tracks in cylinder 
index for each entry in lowest level 
of master index (operand of DCB) 

OMR! optical mark read 

OPTCD! optional services code (operand 
of DCB) 

OS/VS! operating system/virtual 
storage 

OUTIN! output then input (operand of 
OPEN) 

PCI! program-controlled interruption 

PDAB! parallel data access block 

PDSi partitioned data set 

PE! phase encoding (tape recording 
mode) 

PLi PUT macro, locate mode (value of 
MACRF) 


PM! PUT macro, move mode (value of 
MACRF) 
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PO: partitioned organization (value of 
DSORG) 

POUt partitioned organization 
unmovable (value of DSORG) 

PRECL: physical record length (field 
of DCB) 

PRTSPt printer line spacing (operand 
of DCB) 

PS: physical sequential (value of 
DSORG) 

PSU: physical sequential unmovable 
(value of DSORG) 

QISAM: queued indexed sequential 
access methods 

QSAM: queued sequential access method 

RCE: read column eliminate 

RDBACK: read backward (operand of 
OPEN) 

RDI4: record descriptor word 

RECFM: record format (operand of DCB) 

RKPS relative key position (operand of 
DCB) 

RLSE: release unused space (DD 
statement) 

RPS: rotational position sensing 

S: standard format records (value of 
RECFM) 

SDM: segment descriptor word 

SEP: separation (channel separation 
parameter of DD statement or unit 
separation value of UNIT) 

SER: volume serial number (value of 
VOLUME) 

SETL: set lower limit of sequential 
retrieval (QISAM macro instruction) 

SF: sequential forward (operand of 
READ or WRITE) 

SK: skip to a printer channel (operand 
of CNTRL) 

SKP: skip erroneous block (value of 
EROPT) 


SL: IBM standard labels (value of 
LABEL) 

SMSI: size of main-storage area for 
highest-level index (operand of DCB) 

SMSW: size of main-storage work area 
(operand of DCB) 

SP: space lines on a printer (operand 
of CNTRL) 

SS: select stacker on card reader 
(operand of CNTRL) 

SUL: IBM standard and user labels 
(value of LABEL) 

SVC: supervisor call 

SVCLIB: supervisor call library 

SYNAD: synchronous error routine 
address (operand of DCB) 

SYSIN: system input stream 

SYSOUT: system output stream 

T: track overflow option (value of 
RECFM) 

TIOT: task I/O table 

TRC: table reference character 

TRTCH: track recording technique 
(operand of DCB) 

U: undefined length records (value of 
RECFM) 

UCS: universal character set 

UHL: user header label 

UTL: user trailer label 

V: format-V (variable-length) records 
(value of RECFM) 


VB: variable-length# blocked records 
(value of RECFM) 

VBS: variable-length, blocked, spanned 
records (value of RECFM) 

VS: virtual storage or 
variable-length, spanned records 

VTOC: volume table of contents 
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INDEX 


A 


abbreviations 162-164 
.ABE error option 26 
ABEND exit 38-43 

abnormal termination during open, 
close, EOV processing 
ESTAE exit 47 
STAE exit 47 
STAI exit 47 

absolute actual address 18 

allocating space for data sets 
containing 131 

use with direct data sets 125 
aDsolute generation name 147 
ACC error option 26 
access method 2 
basic 51-55 
queued 2,49-51 
selecting 57 
Access Method Services 
DEFINE command 147 
program use of 147 
access techniques 
basic 2,51-55 
queued 2,49-51 
acronyms 162-164 
actual track address 
(MBBCCHHR) 18 

allocating space for data sets 
containing 131 
use with direct data 
sets 125,126 

use with feedback option 125 
address, direct-access storage 
device 

absolute actual 18 

allocating space for data set 
containing 131 

use with direct data sets 125 
direct 124 
indirect 124 
relative 19 

in directories 94-95 
use with direct data sets 125 
AFF affinity, channel 23 
alias entry in directory 

effect of changing directory 
entry 98 
specifying 94 
alignment 

buffer 66 

data control block 43 
allocation 

(see space allocation) 

American National Standard Code 
for Information Interchange 
(see ASCII block prefix; ASCII 
format) 

American National Standard labels 5 
American National Standard Institute 
(see ANSI control character; 

American National Standard labels) 
ANSI control character 
described 161 

device-type considerations 77 
used with chained 
scheduling 85-86 


with format-D records 14 
with format-F ASCII tape 
records 8 

anticipatory buffering 

omitted with basic access 
technique 51 

with queued access technique 49 
ASCII block prefix 

restriction 7,8,14 
with format-D records 14 
with format-F records 7-8 
with format-U records 15 
ASCII format 

restriction for 7-track tape 77 
translating data 
from 1,6,49,86 

translating data to 1,6,49,54 
ASCII tape 

buffer alignment 67 
fixed-length records 8 
undefined-length records 15 
variable-length records 14 
associated data set 

restriction with chained 
scheduling 85 
ATLAS macro 56 
automatic blocking/deblocking 
with queued 
access techniques 49 
automatic cataloging of data 
sets 4 

automatic error options (ERGPT) 
operand of DCB macro 26 
automatic volume 
switching 49,64,65,145 
auxiliary storage (see data set 
storage; direct-access storage; 
magnetic tape volumes) 


B 


backspace 

by BSP macro 82 
by CNTRL macro 80 
basic access technique 

(see also BDAM, BISAM, BPAM, 
and BSAM) 
blocking 52 
buffer acquisition and 
control 66-71 
deblocking 52 
definition of 51-55 
overlapped I/O 53 
using BDW 10 

BCDIC translation to EBCDIC 78 
BDAM (basic direct-access method) 
data set 
(see also 

basic access technique) 
access technique 124 
adding records 127-129 
CHECK macro 55 
creating 126 
dynamic buffering 70,124 
exclusive control for 
updating 125 

extended search option 125 
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feedback option 125 
organisation 124 
processing 123-129 
READ macro 53 
record format 127 
restriction with chained 
scheduling 85 

selecting an access method 57 
sharing data set 45,47 
spanned variable-length 
records 10-14 
SYNAD routine 26 
updating records 127-129 
user labels 2S,129 
WAIT macro 55 

when sharing a data set 45,47 
WRITE macro 54 

BDW (block descriptor word) 10 
BFTEK operand of DCB macro 
BFTEK=A 11,70 
BFTEK=R spanned records 53 
BISAM (basic indexed sequential 
access method) data set 

(see also indexed sequential 
data set) 

dynamic buffering 70 
retrieving 118-122 
sharing a DCB 47,120 
updating 118-122 
when sharing a data set 45,47 
BLDL macro instruction 
build list format 97 
coding example 101 
description 96 
updating a partitioned data 
set 101 

BLKSIZE operand of DCB macro 
description 22 
effect of data check on 6,77 
for writing a short block 91 
for card reader and punch 79 
for undefined-length records 
with QSAM 86 

including block prefix 15 
requirement for direct data 
set 124 

specifying 84,130 
when ignored 134,143 
block count exit routine 36-37 
block, data 6 

block descriptor word (BDW) 10 
block prefix (ASCII) records 
buffer alignment 67 
with format-D records 14-15 
with format-F records 7-9 
with format-U records 15 
block size field (see BLKSIZE field) 
blocking 

automatic 49 
defined 6 

with basic access technique 52 
with fixed-length records 6-9 
with spanned records 10-11 
with variable-length 
records 9-10 

with undefined-length records 15 
boundary alignment 
buffer 67 

data control block 43 
BPAM (basic partitioned access 
method) data set 

concatenation 144-146 
creating 98-100 
defined 2,92-93 


EODAD routine 24 
processing 92-103 
restriction with 

chained scheduling 101 
DCB ABEND exit routine 38 
fixed-length records, 
standard format 7 
search direct operation 86 
retrieving member 100 
space allocation for 134 
updating member 101 
when sharing a data set 45,47 
BSAM (basic sequential access 
method) data set 

as SYSIN/SYSOUT data sets 142 
creating 87 

creating a BDAM data set 126 
determining the length of a 
record 90 

EODAD routine 24,25 
extending 90 

how EODAD routine is entered 24 
overlap of I/O 53,85 
retrieving 88 
to update the directory 97 
updating 89-90 
user labels 28 
user totaling 33-35 
when sharing a data set 45,47 
writing a short block 91 
BSP macro instruction 
description 82 

restriction in EODAD routine 24 
BUFCB operand in DCB macro 67 
buffer 

(see also FREEBUF; FREEDBUF; 
GETBUF; RELSE) 

acquisiton and control 66-76 
alignment 67 
automatic for ISAM 70 
direct 66,70 
dynamic 66,70 
control 69-76 

for basic access technique 66,68 
length (BUFL operand of DCB 
macro) 67,111 

number (BUFNO operand of DCB 
macro) 67,68,85 

pool 67-69 (see also buffer pool) 
releasing 75 
segment 66,69 
truncating 75 

buffer pool (see also BUILD; 

GETPOOL; FREEPOOL) 

automatic construction 66,68 

building 67-68 

coding examples 69 

description 66-67 

explicit 66 

freeing 68 

getting 68 

getting a buffer from 76 
returning a buffer to 76 
returning a dynamic buffer to 76 
static 66 
buffering 58 
anticipatory 

for queued access 
techniqua 4 9 
omitted for basic access 
technique 51 
direct control of 70 
dynamic 66 
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exchange 66,74 
look-ahead 49 
simple 66,71-74 
BUFL operand in DCB macro 
for card punch 79 
for constructing a buffer 
pool 67 
for ISAM 111 
for printer 80 
BUFNO operand in DCB macro 

affecting chained scheduling 85 
affecting performance 85 
when constructing a buffer 
pool 67,68 
when ignored 143 
BUFOFF operand of DCB macro 
with format-DB records 86 
with QSAM or BSAM 8 
with variable-length 
records 14-15 
build list format 96 
(see also BLDL) 

BUILD macro instruction 
dascription 67 
with ISAM data set 111 
BUILDRCD macro instruction 
description 67 
restriction 12 
usage 11,12 


C 


CAMIST macro, use of 147 
capacity for direct-access 
cylinder 5,133 
record 18,126,130 
track 133 

card punch, record format with 79 
card reader 

record format with 79 
relationship with CNTRL macro 79 
restriction with CHTRL macro 79 
carriage control characters 
defined 16,159,161 
specification of in RECFM 
field 77 

CATALOG macro, use of 147 
catalog, system 146 
control volumes 146 
entering a data set name 147 
cataloging data sets 
automatic 4 
defined 1 

for a generation data 
group 147-148 

CCW (see channel command word) 
chained scheduling 

description 76,85,86 
restriction with 
BDAM 85 

calculating record length 90 
CNTRL macro 85 
DOS checkpoint records, 
embedded on tape 85 
format-D records 14 
paper-tape reader 85 
partitioned data set 101 
SKP option 26 
spooled data sets 85 
track overflow 85 
UPDAT operand 85 


updating a sequential data 
set 89 

3525 Card Punch 86 
changing an address in the data 
control block 43,44 
channel command word (CCW) 
creation by OPEN 58 
PCI flag in 85 
use in simple buffering 71 
channel program 

execute (EXCP) 2,57 
number of (NCP) 53,85,143 
channel separation and affinity 
field of DD statement 23 
character set, changing 81 
CHECK macro instruction 
description 55 
to enter EODAD routine 24 
to update a partitioned data 
set 101 

to update a sequential data 
set 89 

use with BDAM 47 
use with SYNAD routine 26,52 
using WAIT instead 
(see WAIT macro instruction) 
when sharing a data set 45,47 
with basic access technique 52 
check routine, examining DECB 55 
checkpoint/restart 

check of JFCBFLAG 36 
restriction for LPALIB 36 
CHKPT macro instruction 

use in end-of-volume exit 
routine 36 

CLOSE macro instruction 
description 61-63 
for multiple data sets 63 
for parallel input 
processing 50-51 
in EODAD routine 24 
restriction with SYNAD 26,61 
temporary close option 61-63 
TYPE=T 61-63 

volume positioning 59,61,62,63 
with partitioned data set 98-100 
with STOW macro 98 
closing a data set 61-63 
CNTRL macro instruction 
device dependence 80 
restrictions 

with BSP macro instruction 82 
with chained scheduling 85 
with DOS checkpoint records 81 
concatenation 
defined 144 

of data sets on RPS devices 146 
of partitioned data sets 144-146 
of sequential data sets 144,146 
of unlike data sets 144,146 
restriction with partitioned data 
sets 101 
control buffer 
(see forms control buffer) 
control character 

(see also CNTRL, PRTOV) 

ANSI 8,14,77,85 
carriage 6,10,16,159,161 
code 159,161 
explained 16 
format-D 14 
format-F 7 
format-U 15 
format-V 10 
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machine 77,86,159,161 
specifying 77,159,161 
with fixed-length records 7 
with undefined-length records 15 
with variable-length records 10 
control section, dummy CDSECT) 43 
control volume 146 
count area 18 

count-data format 18 
count-key-data format 18 
in device overhead 132 
in ISAM index entry format 105 
CREATEV command, use of 130 
cross reference table with direct 
data sets 124 

CSECT statement, use of with DCBD 
macro 43 
cylinder 

allocation by 131 
capacity 4,132 
index 

calculating space requirements 
for 134-135 
definition 103,105 
overflow 

calculating space for 135,137 
defined 103,106 
specifying size 

via CYLOFL parameter 135 
CYLOFL (cylinder overflow) operand 
of DCB macro 

when allocating ISAM data 
set 135 

when creating ISAM data 
set 115 



D-format records 
(see format-D records) 
data access techniques 
(see access techniques) 
data check 

effect on BLKSIZE 6,77 
with SETPRT macro 82 
data control block (DCB) 

ABEND exit 

description 38-40 
when available 24 
where specified 24 
attributes of, 
determining 21-23,43 
changing an address in 43,44 
creation by DCB macro 
instruction 3,19 
description 20-21 
dummy control section 43 
exit 


descr 

iption 

35 


when 

availabl 

e 

24 

when 

used by 

SYSIN/SYSOUT 

where 

i specifi 

ed 

24 

fields 

22-23 



initial 

setting 

of 

44 

modifying 20,43 

-44 


operand 

of DD st 

atement 23 

primary 

sources 

of 



information 20 
sequence of completion 22 
use 3 

when sharing a data set 44 


142 


data definition name (ddname) field 
of DD statement 22 
data definition (DD) statement 
fields 23 

relationship to DCB 21 
relationship to JFCB 21 
use 3 

data errors 25-27 

(see also SYNAD routine) 
data event control block (DECB) 
description of 56 
use of 89 

data management, introduction 
to 1-46 

data mode processing 

relationship with buffers 70 
data set 

characteristics 1-16 
description 22-23 
disposition (DISP) operand 
cataloging 141 
description 23 
overridden by OPEN macro 64 
i dentifica tion 3 
label (DSCB) 3,5,155-158 
(see also magnetic tape 
volumes; data set control 
block; labels, direct-access) 
label (LABEL) field of DD 
statement 23 
like characteristics 144 
name 3 

name (DSNAME) field 22 
organination 2 

(see also BDAM, BISAM, BPAM, 
BSAM, QISAM, and QSAM data 
sets) 

organization (DSORG) operand of 
DCB macro 22 
record formats 6-15 
routing through the input/output 
stream 142-143 
security 1,152 
sharing 

space allocation on direct-access 
volumes 130-141 

estimation 131-134 
for a direct data set 124 
for indexed sequential data 
sets 134-141 
for MSS volume 131 
for partitioned data sets 134 
specifying 130-131 
storage 45 

direct-access 4 
magnetic-tape 5 
SYSIN 142-143 
SYSOUT 142-143 
unlike characteristics 144 
unmovable 

direct organization 124 
resulting from use of 
MMBBCCHHR 19 
specification in DSORG 
operand of DCB 22 
(see also BDAM, BISAM, BPAM, BSAM, 
QISAM, and QSAM data sets) 
data set control block (see DSCB) 

DCB (see data control block) 

DCB ABEND exit 38-40 
DCB macro instruction 20-21 
(see also data control block) 
DCBBLKSI field in DCB 79,80,91 
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DCBD macro instruction 

restriction on use 43 
use 43,44 

DCBLPDA field of DCB 114 
DCBLRECL field of DCB 91 

DCBNCRHI field of DCB 113 

DCBPRECL field of DCB 10 

DCBSYNAD field of DCB 44 

DD statement fields 21-23 
DDNAME (see data definition name 
field) 

deblocking, automatic 49 
DECB (see data event control block) 
defer nonstandard input trailer 
label exit 37 
DEFINE command, use of 147 
defining an FCB image 37 
delete option 

restriction when updating a 
sequential data set 88 
restriction with RKP 109 
use with SETL 115 
deletion 

of indexed sequential data set 
records 109 

of member name using STOW 
macro 98 

DEN (tape density) 77-78 
density, tape 77-78 
DEQ macro, use of 45,47,120 
descriptor word (see block 
descriptor word; record descriptor 
word; segment descriptor word) 
determinate errors 59 
DEVD operand of DCB 

device-class independence 
considerations 84 
restriction with SYSOUT data 
sets 143 
specifying 77 
with BDAM 126 
with SYSOUT data sets 143 
device control for sequential 
data sets 80-82 
device-dependent macro 
instructions 80-82 
device independence 83-85 
device-type considerations for 
data format 

sequential organization 76-80 
DEVTYPE macro, use of 112 
direct-access device 
characteristics 17-19 
direct-access volume 4 
access mechanism 17 
device characteristics 17-19 
devices (see 2305 Fixed Head 
Storage; 2314 Direct Access 
Storage Facility; 2319 Disk 
Storage; 3330 Disk Drive; 3333 
Disk Storage; 3340 Disk Storage; 
3350 Disk Storage) 
labels 4 

record format 6-15,77,80 
track, defined 17 
track addressing 18 
track format 18 
track overflow 19 
write validity check 19 
direct addressing 124 
direct data set 
(see BDAM data set) 
direct organization 
(see BDAM data set) 


directory (see BPAM data set) 
disk drive (see 2305 Fixed Head 
Storage; 2314 Direct Access Storage 
Facility; 2319 Disk Storage; 3330 
Disk Drive; 3333 Disk Storage; 3340 
Disk Storage; 3350 Disk Storage) 
Disk Operating System (see DOS tapes 
with embedded checkpoint records) 
DISP operand 

description 23,64 
for extending sequential data 
set 90 

for indexed sequential data 
set 109 

for partitioned data set 98,99 
for tape 21,33 
specifying 141 

when DISP=SHR for sharing data 
sets 45,120 

when passing a generation 151 
when updating the directory 98 
DOS (Disk Operating System) tapes 
with embedded checkpoint records 
restriction with BSP 82 
restriction with chained 
scheduling 85 
restriction with CNTRL 81 
restriction with POINT 83 
drum storage (see 2305 Fixed Head 
Storage) 

DSCB 

contents of 155-158 
data set label 155-158 
data set security byte 152 
described 4,5,157 
index (format-2) DS2HIRPR field 
of 113 

DSECT statement 43 
DSNAME operand of DD 
statement 22,98,101 
DSORG operand of DCB macro 
described 22 
for direct data set 126 
for sequential data set 87,88 
with CLOSE TYPE=T 62 
with indexed sequential data 
set 115 

with partitioned data 
set 98,99,100 

dummy control section for DCB 43,44 
dummy data set, restriction with 
parallel input processing 50 
dummy record 

with direct data set 126,128 
dynamic buffering 

buffer control 67,124 
for direct data set 124 
for ISAM data set 116,119 
release of using FREEDBUF 76 
(see also READ; RELEX; WRITE) 
specifying 67 


H 

EBCDIC (extended binary coded decimal 
interchange code) 

translation to and from 
ASCII 1,5,49,54,86 

for magnetic-tape volumes 5 
record-format 
dependencies 5-6 
embedded index area 134,136 
end-of-data indicator 64 
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end-of-data routine (EODAD) 24-25 
changing address of in DCB 43-44 
register contents 25 
with basic access technique 52 
with BSP macro 82 
with concatenated data 
sets 144-146 
with GET macro 49 
with queued access technique 49 
end-of-volume 

exit routine 36 
forcing 65 
processing 63-65 
routines, relationship with DCB 
ABEND exit 38,40 

when EODAD routine entered 24-25 
ENQ macro, use of 

when sharing a data 
set 45,47,120 
EODAD routine 24-25 

changing address of in DCB 43-44 
register contents 25 
with basic access technique 52 
with BSP macro 82 
with concatenated data 
sets 144-146 
with GET macro 49 
with queued access technique 49 
EROPT operand of DCB macro 26 
error 

analysis routine CSYNAD) 25-27 
determinate 59 
handling 56 
indeterminate 59 
options, automatic 26 
uncorrectable 25 
error routine (see SYNAD routine) 

ESETL macro instruction 
description 115 
in EODAD routine 25 
when sharing a data set 47 
ESTAE exit, abnormal termination 47 
exceptional condition code (see 
condition, exceptional) 
exchange buffering 74 
exclusive control 

updating direct data sets 125 
when sharing direct data sets 47 
EXCP macro instruction 57 
execute channel program (EXCP) 2 
exit list 27-28 
exit routine 

block count 36 
conventions 28 
data control block (DCB) 35 
DCB ABEND 38-43 
defer nonstandard input trailer 
label 37 

end-of-data 24-25 
end-of-volume 36 
FCB image 37 
JFCBE 35 
list 27-28 

QSAM parallel input 35 
register contents on entry 28 
standard user label 28-33 
synchronous error (SYNAD) 25-27 
user totaling 33-35 
exit routines identified by DCB 24 
EXLST operand of DCB macro 27 
EXTEND option, OPEN macro 
device independence 84 
extending sequential data set 90 
indexed sequential data set 108,109 


QISAM use 60 
specifying 21 
use with SYSIN/SYSOUT 60 
extended binary coded decimal 
interchange code (EBCDIC) 
translation to and from 
ASCII 1,5,49,54,86 

for magnetic-tape volumes 5 
reco rd-format 
dependencies 5~6 

extended American National Standards 
Institute (ANSI) code 161 

(see also ANSI control character) 
extended search option for direct 
data sets 125 


F 


F-format records (see format-F 
records) 

FCB image 
exit 37 

identification in JFCBE 35 
relationship with SETPRT 81 
feedback 

option 125 

with BDAM READ macro 54 
with BDAM WRITE macro 54 
FEOV macro instruction 
description 65 
ignored for SYSIN/SYSOUT data 
sets 65 

restriction with spanned 
records 11,65 

restriction with trailer label 
exit 33 

to enter EODAD routine 24 
file mark, restriction 82 
FIND macro instruction 
description 96-97 
in EODAD routine 25 
updating a partitioned data 
set 101 

when sharing a data set 47 
fixed-length records 6-9 

with parallel input processing 50 
force end-of-volume 
(see FEOV macro instruction) 65 
format-D records 14-15 

restriction with chained 
scheduling 14 
format-F records 6-9 
ASCII tapes 8-9 
standard format 7-8 
with card reader and punch 79 
with parallel input processing 50 
format-FBS records, restriction with 
search direct 86 

format-FBT records, restriction with 
search direct 86 

format-FS records, restriction with 
search direct 86 
format-U records 15 

calculating record length 90 
restriction with chained 
scheduling 85 

with card reader and punch 79 
with parallel input processing 50 
format-UT records, restriction with 
search direct 86 
format-V records 9-13 


170 


0S/VS2 Data Management Services Guide 



block descriptor word 10 
record descriptor word 10 
segment descriptor word 12 
segment control codes 12 
spanned 10-13 
with card punch 79 
with parallel input processing 50 
with user totaling 34 
forms control buffer 
image exit list 37 
FREE operand 63 
FREEBUF macro instruction 
description 76 
to control buffers 66 
FREEDBUF macro instruction 
description 76 
example 121 
for ISAM 120 

when sharing data sets 47 
FREEPOOL macro instruction 68 

when issued for card punch data 
set 7 9 

when issued for printer data 
set 80 

full track-index write option 116 



147 


147,148 

147 


generation 

data set 147 
index 147 

numbers, relative 147-150 
generation data groups 

absolute generation name 
building an index 150 
creating a new 150 
defined 4,147 
entering in the catalog 
relative generation name 
retrieving 151 
GET macro instruction 
description 49 
in EODAD routine 24,25 
restriction with spanned records 
to enter EODAD routine 24 
updating a sequential data 
set 8 9 

when sharing a data set 45 
with format-U records 16 
with parallel input 
processing 50,51 
GETBUF macro instruction 
description 76 
to control buffers 66 
GETPOOL macro instruction 
description 68 
with ISAM data sdt 111 
glossary 162-164 

grouping related control blocks 52 



header label, user 


28-33,157,158 



IBCDASDI utility program 
restriction 130 
IDCAMS, MSS utility program 
use of 131 

IEBCOPY utility program 
use of 102,103 
IEHATLAS utility program 
use of 56 

IEHDASDR utility program 
restriction 130 
IEHLIST utility program 
use of 113,136 
IEHMOVE utility program 
use of 94,95 
IEHPROGM utility program 
use of 136,151 

IHADCB macro instruction label 44 
independent overflow area 
description 106 
specifying 137 
indeterminate errors 59 
i ndex 

area 103 

calculating space for 134-135 
catalog 4 
cylinder 105,117 

calculating space for 134,135 
master 104,105,106 

calculating space for 134,135 
track 104,105,117 

calculating space for 135 
indexed sequential data set (see 
also BISAM and QISAM) adding 
records 107-109 

inserting new records 107 
new records at the 
end 107,109 
areas 103-106 

allocating space 
for 111-114,134-141 
prime 104 
index 105-106 
overflow 106 

buffer requirements 111-114 
creation 116-118 
deleting records 109 
device control 114-115 
full track-index write 
option 116 
retrieving 118-120 
SYNAD routine 27 
updating 118-123 
indexes of the catalog 4 
indirect addressing 124 
INOUT option 

OPEN macro 60 

opening magnetic tape volume 21 
when using POINT macro 82 
INPUT option 

OPEN macro instruction 60 
opening magnetic tape volume 21 
input/output device generation 83 
input/output devices for use with 
sequential data sets 

card reader and punch 78 
direct access 80 
magnetic tape 77 
paper tape reader 78 
printer 79 
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input/output errors* recovering 
from 57 

interrecord gaps CIRGs) 6 
IOB, relationship with SYNAD routine 
for BDAM 26 

IRG (interrecord gap) 6 
ISAM (see indexed sequential data 
set; PISAM; QISAM) 



JES (job entry subsystem) 142-143 
JFCB (job file control block) 21,59 
JFCBE (job file control block 
extension) exit 35 
JFCBFLAG 36 

job file control block (JFCB) 21,59 
job file control block extension 
(JFCBE) exit 35 



key 

class 114 

for direct-access devices 18 
for indexed sequential data 
sets 103-105 

relative key position (RKP) for 
indexed sequential data 
set 109,111,116 
use of when adding records to 
indexed sequential data 
set 107-109 

use of when maintaining an 
indexed sequential data set 109 
use of when retrieving records 
from an indexed sequential data 
set 118-122 

KEYLEN operand of DCB macro 
description 22 
for direct-access device 80 
for direct data set 126 
KN (see WRITE KN) 

KU (see READ KU) 


for end-of-volume processing 64,65 
for forced end-of-volume 
processing 65 
length checking 6 
link field 111,112 

link pack area library, restriction 
for checkpoint 36 
load mode for QISAM 

in SYNAD routine 27 
when sharing a DCB 47 
load mode for BDAM when sharing 
data sets 47 

loading an indexed sequential data 
set 116 

locate mode processing 

defined for buffering 70 
example with simple 
buffering 72,73,74 
relationship with buffers 70 
to process records that exceed 
32,760 bytes 12 

to update a member with QSAM 101 
with GET macro instruction 
creating a sequential data 
set, coding example 89 
simple buffering 71-74,88,89 
with parallel input 
processing 50 

simple buffering 71-74,88,89 
look-ahead buffering 49 
LPALIB, restriction for 
checkpoint 36 
IRECL operand of DCB macro 
described 22 
device dependence 84 
restriction when calculating 
record length 91 
to process records that exceed 
32,760 bytes 12 
with BDAM 126 
with BSAM 91 
with ISAM 

buffer requirements 113 
data set creation 115 
with PUT macro 49,50 
with SYSOUT data set 142 





label exits 28-33 

labels, data set 4,20,21,23 

(see also magnetic-tape volumes; 
labels, direct-access) 
labels, direct-access 

data set control block 155-158 
format 155-158 
user label groups 157,158 
volume label group 155-157 
LABEL parameter of DD statement 
description 23 
specifying password 
protection 152 
specifying standard labels 31 
LEAVE option 

for close processing 61,62 
for concatenated data sets 144 


machine code control 
character 77,86,159,161 
MACRF (macro instruction form) 
operand of DCB macro 
described 23 
device independence 84 
dynamic buffering 120 
for BDAM 126 
processing mode 70 
relationship with WAIT macro 55 
to update a member using QSAM 101 
when sharing a data set 45,47 
magnetic-tape volumes 
defined 5 
density 77-78 
labels 

American National 
Standard 5 
none 4 

nonstandard 4 
standard 4 
user 28-33 
organisation 5 
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positioning 5 

during close processing 61-63 
during end-of-volume 
processing 63,64,65 
record format 6-16,77 
serial number 5 
tapemarks 5 
master catalog 146 
master index 105 
MBBCCHHR (see actual address) 
modes, processing (see data mode; 
locate mode; move mode; 
substitute mode) 
modifying the data control 
block 20,43-44 
move mode processing 

relationship with buffers 70 
use instead of exchange 
buffering 75 

with GET macro instruction 

creating a sequential data 
set 37 

simple buffering 71-73,87 
with parallel input 
processing 50 
with PUT macro instruction 
creating a sequential data 
set 87 

simple buffering 71-74,87 
MSS staging 103 
MSVGP parameter on JCL 
statement 131 

MSWA operand of the DOB macro 113 
multiple data sets 
closing 58 
opening 58 

processing for QISAM 67 
multitasking mode, sharing data 
sets 47,58 
multi volume data set 
with NOTE macro 82 


names 

data set 3 

generation data group 4,147,148 
NCP (number of channel programs) 
operand of the DCB macro 53,85,143 
nonstandard tape labels 4,5 
note list 95 
NOTE macro instruction 
description 82 
restriction with 
BSP macro 82 
multivolume data sets 82 
search direct operation 87 
updating a sequential data 
set 89 

use with partitioned data set 
updating 101 
NTM operand 106 
null segment 13 


O 


offset reading 53 

OMR (see optical mark read) 


OPEN macro instruction 
considerations for 58 
description 60-61 
for parallel input 
processing 50-51 
for simultaneous opening of 
multiple data sets 58 
for updating a sequential data 
set 87 

functions 20,60-61 
restriction with search 
diroct 87 

used for more than one data 
set 58 

volume positioning for EOV 64 
opening a data set 58-61 
OPTCD operand of the DCB macro 
device dependence 85 
with ASCII tapes (0PTCD=Q) 49 
with BDAM 126 
with ISAM 116 
request user totaling 
(0PTCD=T) 33 

0PTCD=H (embedded checkpoints, DOS 
tapes) 81 

MSS staging 103 
0PTCD=M (master index) 106 
0PTCD=T (user totaling) 33 
0PTCD=Z (search direct option) 86 
OUTIN option 

OPEN macro 60 
when opening data set 21 
when using POINT macro 83 
OUTINX option, OPEN macro 21, 60, 84 
output mode 
defined 70 
OUTPUT option 

OPEN macro 60 
when opening data set 21 
when using POINT macro 83 
output stream 142-143 
overflow 

area 103,106 
chain 107 

cylinder (see cylinder overflow) 

independent area 106 

PROTV macro 81 

records 106 

track 

description 19 
effect on chained 
scheduling 85 
restriction on BSP macro 
instruction 82 
restriction with parallel 
input processing 50 
restriction with RPS 
feature 90 

overlap of input/output 

performance improvement 85 
with basic access technique 53 
with partitioned data sets 101 
with sequential data sets 90 
with queued access technique 49 




paging environment, related control 
block group 52 
papei—tape reader 
described 78 
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effect on chained scheduling 85 
record format with 78 
with a 5YNAD routine 27 
parallel 

data access block 
(PDAB) 35,50,51 
input processing 35,50-51 
parameter 1ist 

contents of 39 
use of by DCB ABEND exit 
routine 38-40 

partitioned data set (see BPAM 
data set) 

PASSWORD data set 152 
password protection 152 
PC (card punch) record format 79 
PCI flag 85 
PDABD DSECT 51 
PDAB (parallel data access 
block) 35,50,51 
PDS (see BPAM data set) 
performance improvement 85 
POINT macro instruction 
description 82 
in EODAD routine 25 
restriction with 
BSP macro 83 
multivolume data sets 82 
search direct operation 87 
updating a partitioned data 
set 101 

updating a sequential data 
set 8 9 

prefix, block (see block prefix) 
prefix, key 114 
prime data area 

description 103,104 
space allocation for 134,136,137 
printer 

overflow (PRTOV macro) 81 
record format with 79 
restriction with chained 
scheduling 85 
program, describing the 
processing 23-43 
PRTOV macro instruction 
description 81 
device dependent 84 
when macro will not function 81 
PT (see papei—tape reader) 

PUT macro instruction 
description 49-50 
locate mode 70-74 
used to create a sequential 
data set, coding 
example 87,88 
with format-U records 15 
with indexed sequential data 
set 107-109 

with simple buffering 71-74 
with spanned records 12 
(see also data mode 
processing; locate mode 
processing; move mode 
processing; substitite mode 
processing) 

PUTX macro instruction 
description 50 
device independence 84 
UPDAT mode 74 
updating a sequential data 
set 89 

when sharing a data set 45 
with format-U records 15 


with simple buffering 71-74 
with spanned records 12 
(see also output mode; 
update mode) 


Q 


QISAM data set (see also indexed 
sequential data set) 

EODAD routine 25 
scan mode 120 
sharing 45,47 
SYNAD routine 25-27 
using common buffer pool 68 
QSAM (see also queued access 
technique) 

creating a BDAM data set 126 
parallel input processing 50-51 
performance improvement 85 
restriction with 

spanned records 11 
spanned variable-length 
records 10-12 
SY5IN/SYS0UT data sets 142 
to update a directory 98 
to update a member 101 
user labels 30 
user totaling 33-35 
when sharing a data set 45,47 
with card punch 79 
with printer 80 
queued access technique 
buffer control 66,69 
defined 49 
introduced 2 

processing modes (see data 
mode processing; locate mode 
processing; move mode processing 
substitute mode processing) 


R 


RACF protection 153 
RD (card reader) 79 
RDBACK option 33 

opening magnetic tape volume 21 
restriction for variable-length 
records 60 

restriction with SYSIN/SYSOUT 
data sets 60 

RDW (see record descriptor word) 
read backward (SB operand of READ 
macro) 53 

READ macro instruction 
description 53 
device independence 84 
in SYNAD routine 26 
restriction in EODAD routine 24 
supplying record length 90 
to enter EODAD routine 24 
to update existing records 120 
updating a partitioned data 
set 101 

updating a sequential data 
set 89,90 

when sharing a data set 45,47 
with basic access technique 53 
with format-U records 16 
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with KU (key, update) 

in coding example 121 
RECFM operand of DCB macro 
description 22 
for sequential data sets 77 
selecting 7 
with card punch 78 
with card reader 78 
with control character 77 
with direct-access storage 
device 80 

with magnetic tape 77-78 
with paper tape reader 78 
with printer 79 

with sequential organization 77 
record blocking (see blocking) 
record descriptor word (RDU) 10 
data mode exception for 
spanned records 10 
variable-length records 
format-D 14,15 
when replaced by segment 
descriptor word 12 
record format 6-15 
fixed-length 6-9 
fixed-length for ASCII 8-9 
fixed-length standard 7 
spanned variable-length 10-13 
undefined-length 15 
variable-length 9~15 
record length (LRECL) operand 
of the DCB macro 22,84 
relative block address 
defined 19 

with direct data set 125 
with feedback option 125 
relative generation name 147-150 
relative key position operand 
of the DCB macro 109,111,115 
relative track address 
defined 19 

with direct access 125 
with feedback option 125 
releasing data sets and volumes 63 
RELEX macro instruction 
exclusive control 47 
when sharing data sets 47 
RELSE macro instruction 
defined 75 
to terminate buffer 
processing 66 
reorganization of indexed 
sequential data set 109 
REREAD option 64,65 
restart end-of-voluine exit 
routine 36 
restrictions 

on ASCII records 

block prefix 8,9,14,15 
on 7-track tape 77 
on chained scheduling with 
BDAM 85 

calculating record length 90 
CHTRL macro 85 
DOS checkpoint records 85 
format-D records 14 
papei—tape reader 85 
partitioned data set 101 
SKP option 26 
spooled data sets 85 
track overflow 85,90 
UPDAT operand 85 
updating a sequential data 
set 89,90 


3525 Card Punch 86 
on CHTRL macro 

with BSP macro 82 
with chained scheduling 
with DOS checkpoint 
records 81 
on DCB usage 59-60 
on DCBD macro usage 43,44 
on DOS checkpoint 
records 81-82,85 
on format-D records with 
chained scheduling 14 
on high-level index in 
storage 114 
on NOTE macro with 
BSP macro 82 
multi volume data sets 
search direct operation 
on POINT macro with 
BSP macro 82 
multivolume data sets 
search direct operation 
on reading concatenated 
data sets backward 144 
on user label exit 
routines 29-33 
with search direct 86 
resume load 109,115,117,118 
retrieving a generation 151 
return code 

with block count exit 37 
with user labels 32 
RETURN macro 

relationship in SYNAD 
routine 25 
REWIND option 

for CLOSE macro 61 
for FEOV macro 65 
RKP (relative key 
position 109,111,115 
RLSE parameter of DD 
statement 61 

R0RG1, R0RG2, R0RG3 fields 
of the DCB 109 


85 


82 

87 


82 

87 


routing data sets through the 
input/output stream 142-144 
RPS (rotational position sensing) 
feature 

concatenating data sets on 
non-RPS devices 146 
restriction with track overflow 
records 

variable-length records 9 
when calculating record 
length 90 

R0 record 18,126,130 


S 


save area, user totaling 34 
scan mode for QISAM 

in SYNAD routine 27 
issuing PUTX 120 
scheduling of input/output 
streams 141 

SDW (see segment descriptor word) 
search direct for input 86 
search option, extended 125 
secondary storage (see data set 
storage; direct-access storage; 
magnetic-tape volumes) 
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security, data set 1,152 
segment 

buffer 66,69 
control code 12 
descriptor word 

for spanned records 12 
indicating a null segment 13 
null 13 

selecting an access method 57 
SEP (separation, channel) 23 
sequential data set (see also BPAM, 
BSAM, and QSAfl data sets) 
creation 87 
concatenation 144-146 
extending 90 
retrieving 88 
updating 89 
sequential organization 
defined 2 

device control 80-82 
device independence 83-85 
SETL macro instruction 114-115 
in EODAD routine 25 
when sharing a data set 47 
SETPRT macro instruction 81 
SETPRT routine 37 
sharing data sets 44-46 
sharing DASDs 
simple buffering 

description 71-74 
with parallel input 
processing 50,51 
SKP error option 26 
SMSI operand of the DCB macro 113 
SMSW operand of the DCB 
macro 113 
Sort/merge program 

record restriction 6 
space allocation 

estimating requirements 131-133 
for a direct data set 124 
for an indexed sequential 
data set 134-141 
for an MSS volume 131 
for a partitioned data set 133 
specifying 130-131 
SPACE parameter 23 
spanned records 

basic direct access method 13 
considerations for 11-12 
restriction with parallel input 
processing 50 
restriction with SYSIN data 
sets 12,143 

sequential access method 10 
variable-length 10 
spooling of SYSIN and SYSOUT data 
sets 142-143 
restriction 85 
stacke: selection 

control characters 
for 6,16,160,161 
STACK operand 79 
using CNTRL macro 80 
STAE exit 47 
STAI exit 47 

standard format for fixed-length 
records 7 
standard labels 

direct-access volumes 4,155 
magnetic-tape volumes 4,5 
storage (see direct-access 
storage; magnetic-tape volumes) 


STOW macro instruction 
description 97 
restriction with DCB ABEND 
exit 38 

when sharing a data set 47 
subpool 0, when shared 47 
substitute mode processing 70 
defined for buffering 70 
switching, volume 
automatic 

with end-of-volume 63 
with FEOV macro 65 
with GET macro 49 
restriction with concatenated 
data sets 144 
initiated by CHECK 55 
SYNAD field 

programming consideration 85 
SYNAD routine 

changing address in DCB 44 
description 25-27 
macros used in 56 
programming consideration 85 
relationship with SETL 
option 115 

relationship with DECB 55 
relationship with SYSIN/SYSOUT 
data sets 143 

temporary close restriction 61 
when adding records to ISAM 
data set 109 

when sharing a data set 47 
with basic access technique 52 
with queued access technique 49 
SYNADAF macro instruction 
description 56 
examples 88,89 
use in SYNAD routine 26,27 
SYNADRLS macro instruction 
description 56 
examples 88,89 
use in SYNAD routine 27 
synchronous error routine exit 
(see SYNAD routine) 

SYSIN data set 

FEOV macro ignored for 65 
restriction with 

chained scheduling 85 
parallel input processing 50 
spanned variable-length 
records 12 
user totaling 34 
routing data through input 
stream 142-143 
SYSOUT data set 

FEOV macro ignored for 65 
restriction with 

chained scheduling 85 
label exits 31 
spanned variable-length 
records 12 
user totaling 34 
routing data through output 
stream 142-143 
system generation device 
independence considerations 83 
system input stream 142-143 
system output stream 142-143 
system output writer 142-143 
SYS1, IMAGELIB 

fetching images from 81 
search of 37 
SYS1.LPALIB and 
checkpoint/restart 36 
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m 

table reference character 
(3800) 6,10,16 

tape (see magnetic-tape volumes; 

paper-tape reader) 
tapemark 5 

temporary close 61-62 
totaling area, user totaling 
exit routine 33-35 
track 

addressing 18 
defined 17 
format 

count-data format 18 
count-key-data format 18 
index 103-105,117 
overflow option 
description 19 
effect on chained 
scheduling 85 
restriction of BSP macro 
instruction 82 
restriction with BDAM 129 
restriction with parallel 
input processing 50 
restriction with RPS 
feature 90 
restriction with 
variable-length records 9 
trailer label, user 28-33 
TRC (see table reference character) 
TRTCH 78 

TRUNC macro instruction 
description 75 
to terminate buffer 
processing 66 
truncated blocks, format-F 
records 7 

truncated format-U record 16 
TTR (see address, direct-access 
storage device, relative) 

TYPE=T operand 61-63 


ED 

U-format records (see format-U 
records) 

UCS image 

relationship with SETPRT 81 
UHL (user header label) 28-33 
undefined length records (see 
format-U records) 

UNIT operand of the DD statement 23 
unlabeled magnetic tape 4-5 
UPDAT option (see also update mode) 
EODAD routine entered for 
BSAM 24 

for updating a sequential data 
set 89 

restriction with 

chained scheduling 85 
search direct operation 87 
SYSIN/SYSOUT data sets 60 
opening a data set 21 
updating a sequential data 
set 89 

with spanned records 11 
update mode (see also UPDAT option) 


with format-U records 16 
with PUTX 70 
with simple buffering 74 
user catalog 146,147 
user header label (UHL) 28-33 
user label exit routine 
description 28-33 
exit list entry 30 
restriction for data sets on 
volumes without standard 
labels 31 

restriction for SYSOUT data 
sets 31 

with read backward 31,33 
user totaling exit routine 
control totals 
description 33-35 
exit list entry 34 
how specified 34 
image area address 34 
relationship with 
end-of-volume exit 35,36 
restricted to BSAM, QSAM 33 
save area 34 
totaling area 33-35 
variable-length and spanned 
records 34 

user trailer label (UTL) 28-33 
utility programs, use of 
IBCDASDI 130 
IDCAMS 131 
IEBCOPY 103 
IEHATLAS 57 
IEHDASDR 130 
IEHLIST 113,136 
IEHMOVE 95,158 
IEHPROGM 136,151 
initializing direct-access 
volume 4,130 

UTL (user trailer label) 28-33 


| V | 


variable-length record 
(format-V) 9-13 
segments 9,10,11 
spanned 10-14 

restrictions with SYSIN 
and SYSOUT data sets 12 
special considerations, with user 
totaling 34 
with parallel input 
processing 50 
variable-length record 
(format-D) 14-15 
version increment of generation 
data group 148 
VIO (virtual I/O) 57 
virtual I/O (VIO) 57 
V-format records (see format-V 
records) 
volume 

control 146 
defined 4 
direct-access 4 

(see also direct-access volume) 
disposition (see DISP operand) 
identification operand of 
DD statement 23 
index (see index) 
initializing 4 
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labels (see labels* direct access) 
magnetic-tape (see magnetic tape 
volumes) 

positioning 61-65 
serial number 23 
switching 49*64*65*144 
table of contents (see VTOC) 

VSAM catalog 

for VS2 146,147 
generation data group base 
created in 148 
VS2 systems 

abnormal termination during open* 
close* or EOV processing 59 
action of DISP option 64 
cataloging data sets 146-147 
generation data group base 147 
restriction with 2540 79 

use of VIO (virtual I/O) 57 
VTOC (volume table of 
contents) 4*5 
DSCB 155 

for ISAM data set 105 
initializing 130 
pointer 156 



WAIT macro instruction 
description 55 
example 121 

when sharing a data set 47 
with basic access 
technique 55 
BISAM 55*120 
BDAM 47*55*129 
with QSAM parallel input 
processing 50 
WRITE macro instruction 
add form 126*129 
description 54 
for format-U records 15 
in EODAD routine 24 
in SYNAD routine 26 
programming consideration 84 
supplying record length 91 
update form 128 
updating a partitioned 
data set 101 

updating a sequential data 
set 87*88 

used with BDAM 125*126 
used with note list 95 
when sharing a data set 45*47 
with basic access technique 51*52 
with K (key) 120*122 
with KN (key, 
new) 107*109*122 
writing a short block 91 


write validity check option 19 



1403 Printer 

SETPRT macro for 81 
1600 BPI 78 
2305 Fixed Head Storage 
capacity 132 
overhead formula 133 
programming 
considerations 129 
2314 Direct Access 
Storage Facility 
capacity 132 
overhead formula 133 
2319 Disk Storage 
capacity 132 
overhead formula 133 
2400 Magnetic Tape Units 
recording density 78 
2540 Card Read Punch 
chained scheduling 
restriction 86 
punch error correction 79 
3203 Printer SETPRT macro for 81 
3211 Printer 

SETPRT macro for 81 
3330 Disk Drive 
capacity 132 
overhead formula 133 
3333 Disk Storage 
capacity 132 
overhead formula 133 
3340 Disk Storage 
capacity 132 
overhead formula 133 
3350 Disk Storage 
capacity 132 
overhead formula 133 
3375 Disk Storage 
capacity 132 
overhead formula 133 
3380 Disk Storage 
capacity 132 
overhead formula 133 
3400 Magnetic Tape Units 
recording density 78 
3525 Card Punch 

chained scheduling ignored 85 
record format 77 
3800 Printer 

JFCBE exit for 35 
SETPRT macro for 81 
table reference 
character 6*10*16 
7-track tapes 77 
800 BPI 78 
9-track tapes 77 
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